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 and VietinBank).

BIDV and VietinBank: the order moves 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.
Shinhan Bank: a VA can only be created while the order has received no payment, meaning status Pending.

Shinhan Bank: create an extra VA to reissue the QR code

The payer must settle the full order amount in a single transfer, so a Shinhan Bank order never carries a remaining balance to collect. You create an extra VA when you need to reissue the QR code for an unpaid order, typically after the previous QR expired. The new VA keeps the order amount.

Omit amount and the system uses the parent order's amount. If you do send it, it must equal the order's amount exactly - any other value is refused with 422 and the message VA amount must equal the order amount.

Omit duration and it defaults to 86400 seconds (1 day) from the moment you call, capped at 2592000 seconds (30 days).

Parameters

ba_xidstringrequired

Bank account UUID

order_xidstringrequired

Order UUID

amountinteger

Amount. On BIDV it must not exceed the order amount, on Shinhan Bank it must equal the order amount exactly.

va_holder_namestring

VA holder name. Required if custom VA name feature is enabled. Shinhan Bank accepts up to 300 characters; when omitted it falls back to the name registered with the bank.

durationinteger

VA duration in seconds. Shinhan Bank defaults to 86400 seconds (1 day) and caps at 2592000 seconds (30 days). A larger value is silently lowered to 2592000, with no error. Read expired_at in the response for the real deadline.

Default amount for extra VAs

On every bank, an extra VA with amount omitted defaults to the parent order's amount, not the outstanding remainder. To collect exactly the remainder, work it out and pass amount. On a BIDV open order (amount null) an extra VA gets an amount of 0. On VietinBank, pass the amount you expect for that VA, because a transfer larger than the VA amount is not matched.

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

VietinBank needs identified-account collection registered

A VietinBank account that is not registered for identified-account collection returns 422 vietinbank_va_order_not_enabled, even when the order already exists. If you hit this error, contact SePay for support.

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
400	-	Shinhan Bank: `The selected bank account must be an Enterprise account`. The Shinhan account has not been set up for the API connection by SePay
422	`invalid_state`	Order status does not allow creating a VA (only `Pending`, or `Partially` for BIDV and VietinBank)
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_state`	Shinhan Bank: the parent order has no amount to register with the bank
422	`validation_error`	Shinhan Bank: `amount` was sent but does not equal the order's `amount`
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.
500	`shinhan_error`	Shinhan Bank: unexpected error while registering the VA. Contact SePay support.
503	`shinhan_connection_error`	Shinhan Bank: service temporarily disrupted. Please try again in a few minutes.