Order VAs API quick start

Create VA orders and receive payments via webhook. Supports BIDV (enterprise), Sacombank (personal/household business) and Vietcombank (enterprise/household business).

||
Production only

The Order VAs API is Production only: test directly on Live with a BIDV enterprise, Sacombank personal/household business, or Vietcombank enterprise/household business account linked to your SePay company.

Create unique VA numbers per order. Customers transfer to the VA, SePay auto-matches and sends a webhook.

Supported Banks

BIDVSacombankVietcombank
Account typeEnterprisePersonal / HouseholdEnterprise / Household
VA prefix (va_prefix)Not neededRequiredNot needed
Terminal ID (tid)Not neededNot neededRequired
Amount (amount)OptionalRequiredRequired
order_code max50 chars50 chars15 chars
Partial paymentYesNo (exact amount only)No (exact amount only)
Sacombank and Vietcombank: exact amount only

Sacombank and Vietcombank do not support partial payment. Orders only transition from Pending to Paid or Cancelled.

Vietcombank: `tid` required per order

Every Vietcombank order must be tied to a specific terminal via the tid parameter. If you don't have a terminal yet, see how to add a terminal for a Vietcombank enterprise/household business account. Call List Terminals to fetch a valid tid before creating an order. tid must be the raw Vietcombank-issued Terminal ID (e.g. 20933557), not the SePay xid UUID.

Statuses

Order Status
Rendering diagram...
VA Status
Rendering diagram...

Endpoints

GET
https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/orders
POST
https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/orders
GET
https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/orders/{order_xid}
DELETE
https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/orders/{order_xid}
POST
https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/orders/{order_xid}/va
DELETE
https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/orders/{order_xid}/va/{va_number}
GET
https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/prefixes
GET
https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/prefixes/{va_prefix}
GET
https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/terminals

Payment Flow via VA

Order VA Integration Flow
Rendering diagram...

Integration Steps

Prerequisites

  • Create an API Token
  • A bank account linked on SePay:
    • BIDV: enterprise account
    • Sacombank: personal or business account, merchant activated
    • Vietcombank: enterprise or household business account with at least one terminal (see how to add a terminal, or fetch the list via List Terminals)
  • Get the account UUID from Bank Accounts API

Fetch VA Prefixes (Sacombank) or Terminals (Vietcombank)

BIDV does not need this step. Skip to the next step.

Create Order

cURL
1
2
3
4
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"}'
Response 201
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "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://qr.sepay.vn/img?acc=963NQDORD1234567890AB&bank=BIDV&amount=500000&template=compact"
  }
}

Display to Customer

From the response, show the customer:

  • Account number: va_number (VA number to transfer to)
  • Amount: amount
  • QR code: qr_code or qr_code_url
  • Expiry: expired_at (if set)

Receive Payment Notification

When the customer transfers successfully, SePay sends a webhook to your configured URL. The transaction will contain a code field matching the order's order_code.

See webhook configuration for details.

Check Order Status

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

Order statuses:

  • Pending: awaiting payment
  • Paid: fully paid
  • Partially: partially paid (BIDV only)
  • Cancelled: cancelled

Key Parameters

ParameterRequiredDescription
va_prefixYes (Sacombank)VA prefix. Not used for BIDV or Vietcombank.
tidYes (Vietcombank)Raw Vietcombank-issued Terminal ID. Not used for BIDV or Sacombank.
order_codeNoOrder code (6-50 chars, Vietcombank max 15). Auto-generated if omitted.
amountYes (Sacombank, Vietcombank)Amount (VND). Only BIDV allows it to be optional.

See all parameters

Multiple Payments (BIDV only)

BIDV supports adding VAs to orders in Pending or Partially status. When the cumulative paid amount reaches the order's amount, the order becomes Paid; in between it stays in Partially. Sacombank and Vietcombank do not support Partially: their orders move directly from Pending to Paid on payment.

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

Previous page
—
Next page
—