Quick Start

Create VA orders and receive payments via webhook. Supports BIDV and Sacombank.

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

Supported Banks

BIDVSacombank
Account typeEnterprisePersonal / Business
VA prefix (va_prefix)Not neededRequired
Amount (amount)OptionalRequired
Partial paymentYesNo (exact amount only)
Sacombank: exact amount only

Sacombank does not support partial payment. Orders only transition from Pending to Paid or Cancelled.

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}

Payment Flow via VA

VA Order 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
  • Get the account UUID from Bank Accounts API

Fetch VA Prefixes (Sacombank only)

BIDV

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

Every Sacombank order requires a va_prefix. Fetch the prefix list:

Bash
1
2
curl -X GET "https://userapi.sepay.vn/v2/bank-accounts/{ba_uuid}/prefixes" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
200 OK
{
  "status": "success",
  "data": [
    {
      "va_prefix": "SEP200001WEB",
      "store_id": "WEB",
      "store_name": "NGUYEN VAN A",
      "status": "active",
      "created_at": "2026-03-20 09:00:00"
    }
  ]
}

See VA Prefixes

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.
order_codeNoOrder code (6-50 chars). Auto-generated if omitted.
amountYes (Sacombank)Amount (VND). BIDV: optional.

See all parameters

Multiple Payments (BIDV only)

BIDV supports adding VAs to orders in Pending or Partially status. When all VAs are paid, the order becomes Paid. Sacombank does not support this.

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
—