Bắt đầu nhanh với SePay CLI

Thiết lập SePay CLI trên sandbox và nhận webhook đầu tiên về handler trên máy bạn, không cần URL công khai, tunnel hay giao dịch thật.

||

Yêu cầu trước khi bắt đầu

  • Tài khoản my.sepay.vn. Công ty cần bật Test mode (chế độ thử nghiệm); SuperAdmin, Admin hoặc người dùng có quyền Developer bật được (xem Test mode).
  • Đã cài SePay CLI. sepay version in ra số phiên bản là được.

1. Đăng nhập CLI

Đăng nhập CLI bằng tài khoản my.sepay.vn của bạn:

$ sepay loginOpen your browser to authenticate. Your code: WDJB-MJHTOpening https://my.sepay.vn/...✓ Logged in as dev@congty.vnadd another account with: sepay login --profile <name>

CLI in một mã (WDJB-MJHT ở ví dụ trên) và mở trang Kết nối thiết bị trên my.sepay.vn. Nhập mã đó rồi bấm Tiếp tục. Dòng ✓ Logged in as hiện ra khi đăng nhập xong.

Trang Kết nối thiết bị trên my.sepay.vn: ô Mã thiết bị và nút Tiếp tục
Nhấn để phóng to
Nhập mã CLI in ra vào ô Mã thiết bị rồi bấm Tiếp tục.

2. Khởi tạo sandbox và webhook

Tạo một tài khoản ngân hàng sandbox kèm một webhook chỉ để lắng nghe:

$ sepay sandbox init --with-webhook-listen --yesenv: sandboxCreated bank account 832529c1-xxxx-xxxx-xxxx-fa163e2f7c98 (ACB).Created listen-only webhook 5f0e2a7b-xxxx-xxxx-xxxx-fa163e2f7c98.832529c1-xxxx-xxxx-xxxx-fa163e2f7c98

Dòng cuối là xid của tài khoản ngân hàng sandbox, bước 5 sẽ cần đến. Quên thì xem lại bằng sepay bank-account list. Lần sau dùng lại xid này: chạy lại sandbox init sẽ tạo thêm một tài khoản và một webhook mới.

3. Chạy handler nhận webhook

Nếu ứng dụng của bạn đã chạy trên máy, bỏ qua bước này và trỏ --forward ở bước 4 tới nó. Nếu chưa, dùng một handler tối thiểu:

PHP

PHPPHP
1
2
3
4
5
6
<?php
// handler.php
error_log('Nhận webhook: ' . file_get_contents('php://input'));
header('Content-Type: application/json');
echo json_encode(['success' => true]);
?>

Node.js

JSJavaScript
1
2
3
4
5
6
7
8
9
10
11
// handler.js
const http = require('http');
http.createServer((req, res) => {
let body = '';
req.on('data', chunk => { body += chunk; });
req.on('end', () => {
console.log('Nhận webhook:', body);
res.writeHead(200, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({ success: true }));
});
}).listen(3000);

Chạy handler trong một terminal riêng và để nó chạy. Với PHP:

$ php -S localhost:3000 handler.php

Với Node.js:

$ node handler.js

4. Lắng nghe webhook và chuyển tiếp tới handler

Mở thêm một terminal, nhận webhook sandbox và chuyển tiếp tới handler ở cổng 3000:

$ sepay webhook listen --forward localhost:3000 --printenv: sandboxDelivering for: ACB · 0000000001 · NGUYEN VAN A (sandbox)Any other bank account of this company produces no events.✓ Listening for sandbox events → http://localhost:3000/   (Ctrl+C to stop · retries+enter to manage)

5. Tạo giao dịch thử

Trong một terminal khác (không phải terminal đang chạy handler hay webhook listen), giả lập một giao dịch tiền vào 50.000 đ. Thay <bank-account-xid> bằng xid tài khoản ở bước 2. Lệnh in xid của giao dịch vừa tạo:

$ sepay sandbox simulate payment_in --bank-account <bank-account-xid> --amount 50000 --code DH1709env: sandboxSimulated payment_in event.a41c9e02-xxxx-xxxx-xxxx-fa163e2f7c98

--code điền sẵn mã thanh toán vào webhook (khác gì với nhận diện mã từ nội dung chuyển khoản).

6. Kiểm tra kết quả

Quay lại terminal đang chạy sepay webhook listen. Mỗi webhook hiện một dòng, kèm payload vì có --print:

14:22:07  payment_in   → http://localhost:3000/   200   12ms   txn=a41c9e02-xxxx-xxxx-xxxx-fa163e2f7c98   wh=5f0e2a7b-xxxx-xxxx-xxxx-3c9d81e04b6a  { "accountNumber": "...", "accumulated": 0, "code": "DH1709", ... }

200 là HTTP status handler của bạn trả về, txn= là xid của giao dịch vừa tạo.

Lỗi thường gặp

Exit code khác: xem Exit code và mã lỗi.