Order-based VA API for BIDV Business Accounts

The Order-based Virtual Account (VA) API is an automated payment confirmation solution for BIDV business bank accounts. Instead of using a fixed VA, each order is assigned a unique VA with an exact matching amount.

What can you do with this API?

SePay allows you to perform the following queries with order-based VAs:
- Get the list of orders
- Create a new order
- Get order details
- Create an additional VA for an order
- Cancel an order
- Cancel an order’s VA

Getting started

API URL

[https://my.sepay.vn/userapi/bidv/{bank_account_id}](https://my.sepay.vn/userapi/bidv/{bank_account_id})

To use the order-based VA API, you need to:
- Create an API Token to authenticate your API requests.
- Obtain the bank_account_id of the BIDV business account from the Bank Accounts API or directly from the bank account management interface on SePay.
  Payment method screen

Partial Payment

SePay supports partial payments for orders via Virtual Accounts (VAs). When using this feature:
- You can create an order with the full amount, but allow customers to pay in installments by:
  - Setting the amount smaller than the order amount when creating a new VA
  - Setting the amount to null so the VA can receive multiple payments with any amount until the total reaches the order amount
- When the customer makes a partial payment, the order status changes to Partially
- When the total paid amount reaches the full order amount, the order status automatically changes to Paid and the VA will no longer accept payments
This feature is especially useful for high-value orders or when customers need to pay in installments.

Get order list

GET

/userapi/bidv/123456/orders

Content-Type: application/json
Authorization: Bearer {token}

bash

RESPONSE

{
  "status": "success",
  "data": {
    "orders": [
      {
        "id": "b64247d3-c343-11ef-9c27-52c7e9b4f41b",
        "order_code": "ORD123456789",
        "amount": 2000,
        "paid_amount": 2000,
        "status": "Paid",
        "created_at": "2024-12-26 11:41:46",
        "bank_name": "BIDV",
        "account_number": "1234567890",
        "account_holder_name": "NGO QUOC DAT",
        "va": [
          {
            "va_number": "963NQDORDRSIKYXYPTZ",
            "va_holder_name": "NGO QUOC DAT",
            "amount": 2000,
            "status": "Paid",
            "expired_at": "2024-12-26 11:51:45",
            "paid_at": "2024-12-26 11:42:12"
          }
        ]
      }
    ],
    "pagination": {
      "total": 1,
      "per_page": 20,
      "current_page": 1,
      "last_page": 1
    }
  }
}

Create a new order

POST

/userapi/bidv/123456/orders

Content-Type: application/json
Authorization: Bearer {token}

Request parameters

Name	Type	Required	Description
`amount`	number/null	Required	Order amount; set to null to allow unlimited payment amount.
`order_code`	string	Not required	Order code.
`duration`	number/null	Not required	Order validity time (in seconds). Set to null to have no payment time limit. Default is 600 seconds (10 minutes), maximum is 31,536,000 seconds (1 year).
`va_holder_name`	string	Not required	VA account holder name (only uppercase letters, digits and spaces, max 70 characters).
`with_qrcode`	boolean	Not required	Request to generate a QR Code.

Note

The va_holder_name parameter is only supported for BIDV business accounts that have the custom display name feature enabled by SePay. Please contact SePay support to enable this feature.

bash

RESPONSE

{
  "status": "success",
  "message": "Order created successfully",
  "data": {
    "order_id": "f23cc0fe-c343-11ef-9c27-52c7e9b4f41b",
    "order_code": "ORD123456789",
    "va_number": "963NQDORDZVTBPJ3Z7H",
    "va_holder_name": "NGO QUOC DAT",
    "amount": 2000,
    "status": "Pending",
    "bank_name": "BIDV",
    "account_holder_name": "NGO QUOC DAT",
    "account_number": "1234567890",
    "expired_at": "2024-12-26 11:53:26",
    "qr_code": "data:image/png;base64,...==",
    "qr_code_url": "https://qr.sepay.vn/img?acc=..."
  }
}

Order details

GET

/userapi/bidv/123456/orders/{order_id}

Content-Type: application/json
Authorization: Bearer {token}

Retrieve detailed information of an order by ID.
Path parameters
Name Type Required Description
order_id
string Required
Order ID

Name	Type	Required	Description
`order_id`	string	Required	Order ID

bash

RESPONSE

{
  "status": "success",
  "data": {
    "id": "b64247d3-c343-11ef-9c27-52c7e9b4f41b",
    "order_code": "ORD123456789",
    "amount": 2000,
    "paid_amount": 2000,
    "status": "Paid",
    "created_at": "2024-12-26 11:41:46",
    "bank_name": "BIDV",
    "account_number": "1234567890",
    "account_holder_name": "NGO QUOC DAT",
    "va": [
      {
        "va_number": "963NQDORDRSIKYXYPTZ",
        "va_holder_name": "NGO QUOC DAT",
        "amount": 2000,
        "status": "Paid",
        "expired_at": "2024-12-26 11:51:45",
        "paid_at": "2024-12-26 11:42:12"
      }
    ]
  }
}

Create an additional VA

POST

/orders/{order_id}/va

Content-Type: application/json
Authorization: Bearer {token}

Create an additional VA for an existing order.
Path parameters
Name Type Required Description
order_id
string Required
Order ID

Name	Type	Required	Description
`order_id`	string	Required	Order ID

Request parameters

Name	Type	Required	Description
`amount`	number/null	Required	VA amount: - Defaults to the order amount. - Can be set smaller than the order amount to allow partial payments. - Set to null so the VA can receive multiple payments until the order amount is fully paid.
`va_holder_name`	string	Not required	VA account holder name (only uppercase letters, digits and spaces, max 70 characters).
`duration`	number/null	Not required	VA validity time (in seconds). Set to null for no payment time limit. - Default is 600 seconds (10 minutes). - Maximum is 31,536,000 seconds (1 year).

bash

RESPONSE

{
  "status": "success",
  "message": "VA created successfully",
  "data": {
    "va_number": "963NQDORD8DTYFPW5MV",
    "va_holder_name": "NGUYEN VAN A",
    "amount": 500000,
    "status": "Unpaid",
    "expired_at": "2024-12-26 11:55:55"
  }
}

Cancel an order

DELETE

/orders/{order_id}

Content-Type: application/json
Authorization: Bearer {token}

Path parameters
Name Type Required Description
order_id
string Required
Order ID

Name	Type	Required	Description
`order_id`	string	Required	Order ID

Cancel a VA

DELETE

/orders/{order_id}/va/{va_number}

Content-Type: application/json
Authorization: Bearer {token}

Path parameters

Name	Type	Required	Description
`order_id`	string	Required	ID của một đơn hàng
`va_number`	string	Required	Số va

Handle payment notification Webhooks

When a customer successfully pays into an order’s VA, SePay will send a webhook notification to your website. The webhook payload includes a code field that contains the order code of that VA.
Example webhook payload when a VA is paid:

RESPONSE

{
  "id": 92704,
  "gateway": "BIDV",
  "transactionDate": "2024-01-07 14:02:37",
  "code": "ORD123456789",
  "transferAmount": 2277000,
  "transferType": "in"
}

Your website should check the code field to determine which order was paid and update its status accordingly.
For details on how to set up and handle webhooks, see Webhook Creation Guide.

Status definitions

Order status
Status Description
Pending Order not yet paid
Paid Order has been paid
Partially Order partially paid
Cancelled Order has been cancelled
VA status
Status Description
Unpaid VA not yet paid
Paid VA has been paid
Cancelled VA has been cancelled

Status	Description
Pending	Order not yet paid
Paid	Order has been paid
Partially	Order partially paid
Cancelled	Order has been cancelled

Status	Description
Unpaid	VA not yet paid
Paid	VA has been paid
Cancelled	VA has been cancelled

Request limits

SePay rate limits order-based API requests as follows:
- 2 requests/second per IP
- Exceeding the limit returns response code 429
- The X-SePay-UserApi-Retry-After header indicates how long to wait before retrying

Error codes

SePay may return the following error codes:
HTTP Code Description Cause
400
Bad Request
Invalid or missing parameters
401
Unauthorized
Invalid token
404
Not Found
Resource not found
429
Too Many Requests
Rate limit exceeded

HTTP Code	Description	Cause
400	Bad Request	Invalid or missing parameters
401	Unauthorized	Invalid token
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded

Create an order with no amount and time limits

You can create an order with no limits on amount and payment time by:
- Setting amount to null so the order and its VAs can receive multiple payments
- Setting duration to null so the order has no payment time limit
Example:
bash
After creating an order, you can create a new VA for the order by calling the Create an additional VA API.