Create a New Order
https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/ordersRequest Body (JSON or form-data)
Bank account UUID
Vietcombank Terminal ID (required for Vietcombank accounts). Fetch via GET /bank-accounts/{ba_xid}/terminals. This is the raw Vietcombank-issued Terminal ID, not the SePay xid UUID.
VA prefix (required for Sacombank accounts). Example SEP200001WEB. Not used for BIDV, Vietcombank or VietinBank.
Order code (alphanumeric, 6-50 chars). SePay normalises it to upper case, so a lower-case code comes back upper-cased. Auto-generated if empty, as 10 upper-case characters. Vietcombank limits to 15 characters max.
Amount (positive integer, max 12 digits). Required for Sacombank and Vietcombank accounts (exact amount only), and for VietinBank accounts (underpayment accepted, overpayment rejected). Optional for BIDV.
VA holder name. Only for BIDV enterprise accounts (contact SePay to enable custom VA name). Uppercase A-Z, digits 0-9, spaces. Not supported by Sacombank, Vietcombank or VietinBank.
VA duration in seconds
Include QR code in response (0 or 1)
QR code template
Bank-specific differences
| Parameter | BIDV | Sacombank | Vietcombank | VietinBank |
|---|---|---|---|---|
tid | Not needed | Not needed | Required. See List Terminals. | Not needed |
va_prefix | Not needed | Required. See VA Prefixes. | Not needed | Not needed |
amount | Optional | Required (exact amount only) | Required (exact amount only) | Required (underpayment accepted, overpayment rejected) |
order_code | 6-50 chars | 6-50 chars | 6-15 chars | 6-50 chars |
va_holder_name | BIDV enterprise only (feature must be enabled, contact SePay) | Not supported | Not supported | Not supported |
Sacombank and Vietcombank do not support partial payment. Orders only transition from Pending to Paid or Cancelled.
A VietinBank enterprise account must be registered for identified-account collection with VietinBank before it can create orders. An unregistered account returns 422 vietinbank_va_order_not_enabled. If you hit this error, contact SePay for support.
A VietinBank order always requires an amount, but accepts underpayment: the order moves to Partially and the VA keeps accepting until the total is reached. A transfer above amount is not matched to that VA: the money still lands in the real account, but the order does not move to Paid.
tid must be the raw Vietcombank-issued Terminal ID (e.g. 20933557), not the SePay xid UUID. Fetch valid tid values via List Terminals before creating the order; if you don't have a terminal yet, see how to add a terminal for a Vietcombank enterprise/household business account. Sending a UUID returns 422 invalid_tid_format. If the tid does not belong to the bank account, SePay returns 422 invalid_tid.
Code Examples
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"
}
}Errors
| HTTP | error_code | Description |
|---|---|---|
| 400 | - | BIDV: Bank account is not an enterprise account |
| 400 | - | Sacombank: Merchant not activated for this account |
| 400 | - | Sacombank: va_prefix is invalid or not activated |
| 400 | - | VietinBank: Bank account is not an enterprise account |
| 409 | duplicate | Duplicate order_code |
| 422 | validation_error | Validation error |
| 422 | vietinbank_va_order_not_enabled | VietinBank: account is not registered for identified-account collection, or SePay has not opened the feature yet |
| 422 | invalid_tid_format | Vietcombank: tid is the SePay xid UUID instead of the raw Terminal ID |
| 422 | invalid_tid | Vietcombank: tid does not belong to this bank account |
| 500 | vcb_error | Vietcombank: unexpected error while creating the order. Contact SePay support. |
| 503 | vcb_connection_error | Vietcombank: service temporarily disrupted. Please try again in a few minutes. |