Create VA for Order API

Create a New VA for Order

POST

https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/orders/{order_xid}/va

Allowed order statuses

Order must be Pending, or Partially (BIDV only).

BIDV: only BIDV moves the order to Partially when the cumulative received amount is below amount. Extra VAs can accumulate until the full amount is reached, then the order becomes Paid.
Sacombank and Vietcombank: the order moves directly Pending → Paid on the first payment. Extra VAs serve as parallel payment channels — whichever VA is paid first closes the order.

Parameters

ba_xidstringrequired

Bank account UUID

order_xidstringrequired

Order UUID

amountinteger

Amount, must not exceed order amount

va_holder_namestring

VA holder name. Required if custom VA name feature is enabled.

durationinteger

VA duration in seconds

Default `amount` for extra VAs

Extra VAs on Sacombank and Vietcombank: if amount is omitted, the system defaults to the parent order's amount — an extra VA on these banks is effectively a repeat payment channel for the same amount, not a remainder-collector.

Extra Vietcombank VAs also inherit tid from the parent order, no need to resend.

Code Examples

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)

Response 201 - VA created successfully

{
  "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"
  }
}

statusstring

messagestring

dataobject

Errors

HTTP	error_code	Description
422	`invalid_state`	Order status does not allow creating a VA (only `Pending`, or `Partially` for BIDV)
500	`vcb_error`	Vietcombank: unexpected error while creating the VA. Contact SePay support.
503	`vcb_connection_error`	Vietcombank: service temporarily disrupted. Please try again in a few minutes.