API VA theo đơn hàng chỉ hỗ trợ trên Production. Cần thực hiện trực tiếp trên Production với tài khoản BIDV doanh nghiệp, Sacombank cá nhân/hộ kinh doanh hoặc Vietcombank doanh nghiệp/hộ kinh doanh đã liên kết.
Tạo số VA riêng cho mỗi đơn hàng. Khách chuyển khoản vào VA, SePay tự động khớp và gửi webhook.
Ngân hàng hỗ trợ
| BIDV | Sacombank | Vietcombank | |
|---|---|---|---|
| Loại tài khoản | Doanh nghiệp | Cá nhân / HKD | Doanh nghiệp / HKD |
Tiền tố VA (va_prefix) | Không cần | Bắt buộc | Không cần |
Terminal ID (tid) | Không cần | Không cần | Bắt buộc |
Số tiền (amount) | Tùy chọn | Bắt buộc | Bắt buộc |
order_code tối đa | 50 ký tự | 50 ký tự | 15 ký tự |
| Thanh toán một phần | Có | Không (chỉ đúng số tiền) | Không (chỉ đúng số tiền) |
Sacombank và Vietcombank không hỗ trợ thanh toán một phần. Đơn hàng chỉ chuyển Pending sang Paid hoặc Cancelled.
Mỗi đơn hàng Vietcombank phải gắn với một terminal cụ thể qua tham số tid. Nếu chưa có terminal, xem cách thêm terminal cho tài khoản Vietcombank doanh nghiệp/hộ kinh doanh. Gọi Danh sách terminal để lấy tid hợp lệ trước khi tạo đơn hàng. tid là Terminal ID gốc do Vietcombank cấp (ví dụ 20933557), không phải xid UUID của SePay.
Trạng thái
Các endpoint
https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/ordershttps://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/ordershttps://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/orders/{order_xid}https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/orders/{order_xid}https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/orders/{order_xid}/vahttps://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/orders/{order_xid}/va/{va_number}https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/prefixeshttps://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/prefixes/{va_prefix}https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/terminalsLuồng thanh toán qua VA
Các bước tích hợp
Chuẩn bị
- Tạo API Token
- Tài khoản ngân hàng đã liên kết trên SePay:
- BIDV: tài khoản doanh nghiệp
- Sacombank: tài khoản cá nhân hoặc hộ kinh doanh, merchant đã kích hoạt
- Vietcombank: tài khoản doanh nghiệp hoặc hộ kinh doanh, đã có ít nhất một terminal (xem cách thêm terminal hoặc lấy danh sách qua Danh sách terminal)
- Lấy UUID tài khoản từ API Tài khoản ngân hàng
Lấy tiền tố VA (Sacombank) hoặc terminal (Vietcombank)
Tạo đơn hàng
curl -X POST "https://userapi.sepay.vn/v2/bank-accounts/{ba_uuid}/orders" \-H "Content-Type: application/json" \-H "Authorization: Bearer YOUR_API_TOKEN" \-d '{"amount": 500000, "order_code": "DH20250001", "with_qrcode": "1"}'
{"status": "success","message": "Order created successfully","data": {"id": "b2c3d4e5-f6a7-8901-bcde-f12345678902","order_code": "DH20250001","va_number": "963NQDORD1234567890AB","va_holder_name": "CONG TY CP TECH VINA","amount": 500000,"status": "Pending","bank_name": "BIDV","account_holder_name": "CONG TY CP TECH VINA","account_number": "1234567890","expired_at": null,"qr_code": "data:image/png;base64,...","qr_code_url": "https://qr.sepay.vn/img?acc=963NQDORD1234567890AB&bank=BIDV&amount=500000&template=compact"}}
Hiển thị cho khách hàng
Từ response, hiển thị cho khách hàng:
- Số tài khoản:
va_number(số VA để chuyển khoản) - Số tiền:
amount - Mã QR:
qr_codehoặcqr_code_url - Thời hạn:
expired_at(nếu có)
Nhận thông báo thanh toán
Khi khách hàng chuyển khoản thành công, SePay gửi webhook đến URL bạn đã cấu hình. Giao dịch sẽ chứa trường code khớp với order_code của đơn hàng.
Xem chi tiết cấu hình webhook.
Kiểm tra trạng thái đơn hàng
curl -X GET "https://userapi.sepay.vn/v2/bank-accounts/{ba_uuid}/orders/{order_uuid}" \-H "Authorization: Bearer YOUR_API_TOKEN"
Trạng thái đơn hàng:
Pending: chờ thanh toánPaid: đã thanh toánPartially: thanh toán một phần (chỉ BIDV)Cancelled: đã hủy
Tham số chính
| Tham số | Bắt buộc | Mô tả |
|---|---|---|
va_prefix | Có (Sacombank) | Tiền tố VA. Không dùng cho BIDV và Vietcombank. |
tid | Có (Vietcombank) | Terminal ID gốc do Vietcombank cấp. Không dùng cho BIDV và Sacombank. |
order_code | Không | Mã đơn hàng (6-50 ký tự, Vietcombank tối đa 15). Tự sinh nếu bỏ qua. |
amount | Có (Sacombank, Vietcombank) | Số tiền (VND). Chỉ BIDV cho phép tùy chọn. |
Thanh toán nhiều lần (chỉ BIDV)
BIDV hỗ trợ tạo thêm VA cho đơn hàng đang Pending hoặc Partially. Khi tổng số tiền thanh toán đạt đủ amount của đơn hàng, đơn hàng chuyển sang Paid; trong khi đó đơn hàng ở trạng thái Partially. Sacombank và Vietcombank không hỗ trợ trạng thái Partially: đơn hàng chuyển trực tiếp từ Pending sang Paid khi nhận thanh toán.
Hủy đơn hàng hoặc VA
Chỉ hủy được đơn hàng Pending và VA Unpaid. Response: 204 No Content.