Order VAs API quick start

An order VA is a virtual account number dedicated to a single order. The customer transfers to that VA, SePay matches the transaction to the order by its exact amount and sends a webhook to your system.

Supported Banks

BIDV, Sacombank, Vietcombank and VietinBank accounts linked to your SePay company all create order VAs through the same endpoint, but differ in the account type, the required parameters and how they take the money. Read the section for the bank you are integrating.

BIDV

When the customer pays less than amount, the order moves to Partially and the VA keeps accepting payments until the total is reached.

A BIDV enterprise account can also set its own VA holder name through va_holder_name, but the feature has to be enabled first. Contact SePay if you need it.

Sacombank

Every Sacombank order must be tied to a VA prefix. Call VA Prefixes to fetch an active va_prefix before creating the order. The merchant must be activated, otherwise the call returns 400.

Vietcombank

VietinBank

A VietinBank order always carries an amount, but a customer paying less is still recorded: the order moves to Partially and the VA keeps accepting until the total is reached. A VA that has expired, is already paid, or was cancelled takes no further money.

A transfer above the VA amount is not matched: the money still lands in the real account, but the order does not move to Paid. Collecting in instalments on VietinBank means each instalment must be at or below the VA amount.

What VietinBank collected can be refunded through the API.

Statuses

An order also carries its own refund_status field, null until the first refund is issued. It only takes another value on a bank that supports refunds.

Unlike status, this field is recomputed from all of the order's refunds, so it can walk back. See what each value means.

Endpoints

Payment Verification Flow for Order VAs

order_code is the thread tying your own order to the order on SePay. Your website generates the code when the customer checks out, passes it into the create-order call, and the webhook returns it in the code field so you can reconcile. Omit it and SePay generates one, but then you have to store the returned code yourself to match back.

SePay normalises order_code to upper case before storing it. Sending dh20250001 is accepted, but the order is stored as DH20250001, and that is what the response and the webhook return. If your system uses lower-case codes, compare them case-insensitively, or store the value from the response rather than the one you sent.

Refund Flow

Once an order is Paid or Partially, you send what it collected back through the Refunds API. Only VietinBank enterprise accounts that SePay has enabled for refunds can use it today.

A refund does not change the order's status or paid_amount; the order carries a separate refund_status field instead. See Refund an order for the parameters, the state diagram and the error table.

Integration Steps

curl -X POST "https://userapi.sepay.vn/v2/bank-accounts/{ba_uuid}/orders" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{"amount": 500000, "order_code": "DH20250001", "with_qrcode": "1"}'

{
  "status": "success",
  "message": "Order created successfully",
  "data": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678902",
    "order_code": "DH20250001",
    "va_number": "963NQDORD1234567890AB",
    "va_holder_name": "CONG TY CP TECH VINA",
    "amount": 500000,
    "status": "Pending",
    "bank_name": "BIDV",
    "account_holder_name": "CONG TY CP TECH VINA",
    "account_number": "1234567890",
    "expired_at": null,
    "qr_code": "data:image/png;base64,...",
    "qr_code_url": "https://vietqr.app/img?acc=963NQDORD1234567890AB&bank=BIDV&amount=500000&template=compact"
  }
}

curl -X GET "https://userapi.sepay.vn/v2/bank-accounts/{ba_uuid}/orders/{order_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Key Parameters

See all parameters

Partial Payments

A partial payment is a transfer smaller than the order's amount that SePay still records, instead of matching only an exact-amount transfer. The order collects gradually across several transfers until the total is reached.

A first transfer below amount moves the order to Partially, and the paid_amount field holds the running total. The VA keeps accepting, each transfer adding to paid_amount. Once paid_amount reaches amount, the order becomes Paid. You can also create an extra VA on an order in Pending or Partially to collect the remainder.

Compared to a full payment

Bank support

BIDV and VietinBank record underpayments: the order sits at Partially until the full amount is collected.

VietinBank adds one constraint in the other direction: a transfer larger than the VA amount is not matched. The money still lands in the real account, but the order does not move. So when collecting in instalments on VietinBank, each instalment must be at or below the VA amount.

To collect the remainder with an extra VA, work the figure out yourself and pass amount. Omitting amount gives the VA the parent order's amount, not the outstanding remainder, on BIDV too. On a BIDV open order (amount null) an extra VA defaults to an amount of 0.

Sacombank and Vietcombank do not support Partially: their orders move straight from Pending to Paid on payment. They can still take an extra VA on a Pending order, but that VA is a parallel payment channel for the same amount, not a way to collect a remainder.

See Create VA API

Cancel Order or VA

Only Pending orders and Unpaid VAs can be cancelled. Response: 204 No Content.

Cancel Order | Cancel VA

See Also

• Create Order (API reference)
• List Orders
• Refund an order
• VA Prefixes
• List Terminals
• Webhook Configuration