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 or Vietcombank.
Order code (alphanumeric, 6-50 chars). Auto-generated if empty. Vietcombank limits to 15 characters max.
Amount (positive integer, max 12 digits). Required for Sacombank and Vietcombank accounts (exact amount only). 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 or Vietcombank.
VA duration in seconds
Include QR code in response (0 or 1)
QR code template
Bank-specific differences
| Parameter | BIDV | Sacombank | Vietcombank |
|---|---|---|---|
tid | Not needed | Not needed | Required. See List Terminals. |
va_prefix | Not needed | Required. See VA Prefixes. | Not needed |
amount | Optional | Required (exact amount only) | Required (exact amount only) |
order_code | 6–50 chars | 6–50 chars | 6–15 chars |
va_holder_name | BIDV enterprise only (feature must be enabled, contact SePay) | Not supported | Not supported |
Sacombank and Vietcombank do not support partial payment. Orders only transition from Pending to Paid or Cancelled.
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://qr.sepay.vn/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 |
| 409 | duplicate | Duplicate order_code |
| 422 | validation_error | Validation error |
| 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. |