Tạo VA mới cho đơn hàng
https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/orders/{order_xid}/vaĐơn hàng phải ở trạng thái Pending, hoặc Partially (BIDV và VietinBank).
- BIDV và VietinBank: đơn hàng chuyển sang
Partiallykhi tổng số tiền nhận chưa đủamount. Các VA bổ sung có thể tích lũy tới khi đủamountthì đơn hàng chuyểnPaid. - Sacombank và Vietcombank: đơn hàng chuyển trực tiếp
Pending→Paidngay khi nhận thanh toán đầu tiên. Các VA bổ sung dùng để cung cấp nhiều kênh thanh toán song song, VA nào được thanh toán trước sẽ đóng đơn hàng. - Shinhan Bank: chỉ tạo được VA khi đơn hàng chưa nhận thanh toán nào, tức trạng thái
Pending.
Khách hàng phải trả trọn một lần đúng số tiền đơn hàng, nên đơn hàng Shinhan Bank không bao giờ còn phần thiếu để thu thêm. Bạn tạo thêm VA khi cần phát lại mã QR cho đơn hàng chưa ai thanh toán, thường là sau khi QR cũ hết hạn. VA mới giữ nguyên số tiền của đơn hàng.
Bỏ trống amount thì hệ thống lấy amount của đơn hàng gốc. Nếu truyền thì phải bằng đúng amount của đơn hàng - giá trị khác bị từ chối với 422 kèm thông báo VA amount must equal the order amount.
Bỏ trống duration thì mặc định 86400 giây (1 ngày) kể từ lúc gọi, trần 2592000 giây (30 ngày).
Tham số
UUID tài khoản ngân hàng
UUID đơn hàng
Số tiền. Với BIDV không được vượt quá số tiền đơn hàng, với Shinhan Bank phải bằng đúng số tiền đơn hàng.
Tên chủ VA. Bắt buộc nếu đã bật tính năng tùy chỉnh tên VA. Shinhan Bank nhận tối đa 300 ký tự, bỏ trống thì lấy tên đăng ký với ngân hàng.
Thời hạn VA tính bằng giây. Shinhan Bank mặc định 86400 giây (1 ngày) và tối đa 2592000 giây (30 ngày). Giá trị lớn hơn được tự hạ về 2592000, không báo lỗi. Đọc expired_at trong response để biết hạn thật.
Trên mọi ngân hàng, nếu bỏ trống amount thì VA bổ sung mặc định bằng amount của đơn hàng gốc, không phải phần còn thiếu. Muốn thu đúng phần còn thiếu thì tự tính và truyền amount. Đơn hàng mở của BIDV (amount null) cho VA bổ sung amount bằng 0. Với VietinBank, hãy truyền amount đúng bằng số tiền mong đợi của VA đó, vì giao dịch lớn hơn amount của VA không được khớp.
VA bổ sung Vietcombank còn kế thừa tid từ đơn hàng gốc, không cần truyền lại.
Tài khoản VietinBank chưa đăng ký dịch vụ thu hộ qua tài khoản định danh nhận 422 vietinbank_va_order_not_enabled, kể cả khi đơn hàng đã tồn tại. Nếu bạn gặp lỗi này, vui lòng liên hệ SePay để được hỗ trợ.
Code mẫu
curl --request POST \--url https://userapi.sepay.vn/v2/bank-accounts/f9e8d7c6-b5a4-3210-fedc-ba0987654321/orders/b2c3d4e5-f6a7-8901-bcde-f12345678902/va \--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \--header 'content-type: application/json' \--data '{"amount":0,"va_holder_name":"string","duration":0}'
Response (HTTP 201)
{
"status": "success",
"message": "VA created successfully",
"data": {
"va_number": "963NQDORD1234567890CD",
"va_holder_name": "TRAN THI B",
"amount": 500000,
"status": "Unpaid",
"expired_at": "2025-12-19 08:15:00"
}
}Lỗi
| HTTP | error_code | Mô tả |
|---|---|---|
| 400 | - | Shinhan Bank: The selected bank account must be an Enterprise account. Tài khoản Shinhan chưa được SePay cấu hình kết nối API |
| 422 | invalid_state | Trạng thái đơn hàng không cho phép tạo thêm VA (chỉ tạo được cho Pending, hoặc Partially với BIDV và VietinBank) |
| 422 | vietinbank_va_order_not_enabled | VietinBank: tài khoản chưa đăng ký dịch vụ thu hộ qua tài khoản định danh |
| 422 | invalid_state | Shinhan Bank: đơn hàng gốc không có số tiền để đăng ký với ngân hàng |
| 422 | validation_error | Shinhan Bank: có truyền amount nhưng không bằng amount của đơn hàng |
| 500 | vcb_error | Vietcombank: lỗi không xác định khi tạo VA. Liên hệ SePay. |
| 503 | vcb_connection_error | Vietcombank: dịch vụ tạm thời gián đoạn. Vui lòng thử lại sau ít phút. |
| 500 | shinhan_error | Shinhan Bank: lỗi không xác định khi đăng ký VA. Liên hệ SePay. |
| 503 | shinhan_connection_error | Shinhan Bank: dịch vụ tạm thời gián đoạn. Vui lòng thử lại sau ít phút. |