Tạo đơn hàng mới
https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/ordersTham số
UUID tài khoản ngân hàng
Terminal ID Vietcombank (bắt buộc khi tài khoản là Vietcombank). Lấy từ endpoint GET /bank-accounts/{ba_xid}/terminals. Là Terminal ID gốc Vietcombank cấp, không phải xid UUID của SePay.
Tiền tố VA (bắt buộc khi tài khoản là Sacombank). Ví dụ SEP200001WEB. Không dùng cho BIDV, Vietcombank và VietinBank.
Mã đơn hàng (alphanumeric, 6-50 ký tự). SePay chuẩn hoá về chữ in hoa, nên gửi chữ thường sẽ nhận lại bản in hoa. Tự sinh nếu để trống, mã tự sinh dài 10 ký tự in hoa. Vietcombank và Shinhan Bank giới hạn tối đa 15 ký tự.
Số tiền (số nguyên dương, tối đa 12 chữ số). Bắt buộc khi tài khoản là Sacombank, Vietcombank hoặc Shinhan Bank (chỉ nhận đúng số tiền), và khi tài khoản là VietinBank (nhận trả thiếu, từ chối trả vượt). Tùy chọn với BIDV.
Tên chủ VA, tối đa 300 ký tự. BIDV doanh nghiệp vẫn giới hạn riêng tối đa 70 ký tự, chỉ gồm chữ hoa A-Z, số 0-9 và khoảng trắng (liên hệ SePay để bật tính năng tùy chỉnh tên VA). Shinhan Bank nhận tối đa 300 ký tự, không ràng buộc chữ hoa; bỏ trống thì lấy tên đăng ký với ngân hàng. Sacombank, Vietcombank và VietinBank không hỗ trợ.
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.
Bao gồm mã QR trong response (0 hoặc 1)
Mẫu mã QR
Khác biệt theo ngân hàng
| Tham số | BIDV | Sacombank | Vietcombank | VietinBank | Shinhan Bank |
|---|---|---|---|---|---|
tid | Không cần | Không cần | Bắt buộc. Xem Danh sách terminal. | Không cần | Không cần |
va_prefix | Không cần | Bắt buộc. Xem Tiền tố VA. | Không cần | Không cần | Không truyền |
amount | Tùy chọn | Bắt buộc (chỉ nhận đúng số tiền) | Bắt buộc (chỉ nhận đúng số tiền) | Bắt buộc (nhận trả thiếu, từ chối trả vượt) | Bắt buộc (chỉ nhận đúng số tiền) |
order_code | 6-50 ký tự | 6-50 ký tự | 6-15 ký tự | 6-50 ký tự | 6-15 ký tự |
va_holder_name | Chỉ BIDV doanh nghiệp (cần bật tính năng, liên hệ SePay) | Không hỗ trợ | Không hỗ trợ | Không hỗ trợ | Tối đa 300 ký tự, bỏ trống thì lấy tên đăng ký với ngân hàng |
duration | Không giới hạn mặc định | Theo cấu hình | Mặc định 900 giây | Không giới hạn mặc định | Mặc định 86400 giây, tối đa 2592000 giâ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 |
Ba ngân hàng này không hỗ trợ thanh toán một phần. Đơn hàng chỉ chuyển Pending sang Paid hoặc Cancelled.
SePay đăng ký VA Shinhan Bank kèm điều kiện số tiền, nên khách chuyển sai số tiền qua Napas sẽ bị từ chối ngay lúc bấm chuyển, tiền không rời tài khoản của họ.
VA đã quá expired_at vẫn có thể nhận tiền ở ngân hàng trong thời gian ngắn trước khi SePay hủy VA. Khoản tiền đó vẫn được ghi thành giao dịch và gửi qua webhook, nhưng không đóng đơn hàng. Bạn cần đối soát thủ công các giao dịch này.
Tài khoản VietinBank doanh nghiệp phải đăng ký dịch vụ thu hộ qua tài khoản định danh với VietinBank thì mới tạo được đơn hàng. Tài khoản chưa đăng ký nhận 422 vietinbank_va_order_not_enabled. Nếu bạn gặp lỗi này, vui lòng liên hệ SePay để được hỗ trợ.
Đơn hàng VietinBank bắt buộc có amount, nhưng chấp nhận trả thiếu: đơn hàng chuyển Partially và VA vẫn nhận tiếp tới khi đủ. Giao dịch lớn hơn amount không được khớp vào VA: tiền vẫn vào tài khoản thật nhưng đơn hàng không tự chuyển Paid.
tid phải là Terminal ID gốc do Vietcombank cấp (ví dụ 20933557), không phải xid UUID của SePay. Lấy tid hợp lệ qua Danh sách terminal trước khi tạo đơn hàng; nếu chưa có terminal, xem cách thêm terminal cho tài khoản Vietcombank doanh nghiệp/hộ kinh doanh. Nếu gửi nhầm UUID, SePay trả 422 invalid_tid_format. Nếu tid không thuộc tài khoản ngân hàng, SePay trả 422 invalid_tid.
Code mẫu
curl --request POST \--url https://userapi.sepay.vn/v2/bank-accounts/f9e8d7c6-b5a4-3210-fedc-ba0987654321/orders \--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \--header 'content-type: application/json' \--data '{"tid":"string","va_prefix":"string","order_code":"string","amount":0,"va_holder_name":"string","duration":0,"with_qrcode":"0","qrcode_template":"compact"}'
Response (HTTP 201)
{
"status": "success",
"message": "Order created successfully",
"data": {
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678902",
"order_code": "ORDER2026001",
"va_number": "963NQDORD1234567890AB",
"va_holder_name": "TRAN THI B",
"amount": 1000000,
"status": "Pending",
"bank_name": "BIDV",
"account_holder_name": "TRAN THI B",
"account_number": "1234567890",
"expired_at": null,
"qr_code": "data:image/png;base64,...",
"qr_code_url": "https://vietqr.app/img?acc=963NQDORD1234567890AB&bank=BIDV&amount=1000000&template=compact"
}
}Lỗi
| HTTP | error_code | Mô tả |
|---|---|---|
| 400 | - | BIDV: Tài khoản không phải loại doanh nghiệp |
| 400 | - | Sacombank: Merchant chưa được kích hoạt |
| 400 | - | Sacombank: va_prefix không tồn tại hoặc đã bị hủy |
| 400 | - | VietinBank: Tài khoản không phải loại doanh nghiệp |
| 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 |
| 409 | duplicate | Trùng order_code |
| 422 | validation_error | Lỗi validation |
| 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, hoặc SePay chưa mở tính năng này |
| 422 | invalid_tid_format | Vietcombank: tid đang gửi UUID xid thay vì Terminal ID gốc |
| 422 | invalid_tid | Vietcombank: tid không thuộc tài khoản ngân hàng này |
| 500 | vcb_error | Vietcombank: lỗi không xác định khi tạo đơn hàng. 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. |