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 versionin 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.

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-fa163e2f7c98Dò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
<?php// handler.phperror_log('Nhận webhook: ' . file_get_contents('php://input'));header('Content-Type: application/json');echo json_encode(['success' => true]);?>
Node.js
// handler.jsconst 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.phpVới Node.js:
$ node handler.js4. 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.