Create Order

Create a new VA order for a BIDV or Sacombank account via SePay API v2.

Create a New Order

POST

https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/orders

Request Body (JSON or form-data)

Field	Type	Required	Description
`va_prefix`	string	Required (Sacombank)	VA prefix (e.g. `SEP200001WEB`). Required for Sacombank. Not used for BIDV. See VA Prefixes.
`order_code`	string	No	Alphanumeric, 6-50 characters. Auto-generated if empty.
`amount`	int	Required (Sacombank)	Positive integer (VND). Required for Sacombank (exact amount only). Optional for BIDV.
`va_holder_name`	string	No (BIDV only)	BIDV only. Custom VA holder name. Requires the feature enabled by SePay. Not supported on Sacombank.
`duration`	int	No	VA validity period in seconds.
`with_qrcode`	string	No	`0` or `1`. Include QR code in response.
`qrcode_template`	string	No	`compact` or `qronly`.

Bank-specific differences

Parameter	BIDV	Sacombank
`va_prefix`	Not needed	Required. See VA Prefixes.
`amount`	Optional	Required (exact amount only)
`va_holder_name`	Yes (requires feature enabled, contact SePay)	Not supported

Code Examples

curl --request POST \
  --url https://userapi.sepay.vn/v2/bank-accounts/f9e8d7c6-b5a4-3210-fedc-ba0987654321/orders \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"va_prefix":"string","order_code":"string","amount":0,"va_holder_name":"string","duration":0,"with_qrcode":"0","qrcode_template":"compact"}'

Response (HTTP 201)

{
  "status": "success",
  "data": {
    "id": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
    "order_code": "DH001",
    "va_number": "9704070012345678",
    "va_holder_name": "NGUYEN VAN A",
    "amount": 500000,
    "status": "Pending",
    "bank_name": "BIDV",
    "account_holder_name": "NGUYEN VAN A",
    "account_number": "2611000000",
    "expired_at": "2026-03-11 10:00:00",
    "qr_code": "data:image/png;base64,...",
    "qr_code_url": "https://qr.sepay.vn/..."
  }
}

Response 201 - Order created successfully

{
  "status": "success",
  "message": "Order created successfully",
  "data": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678902",
    "order_code": "ORDER2026001",
    "va_number": "963NQDORD1234567890AB",
    "va_holder_name": "TRAN THI B",
    "amount": 1000000,
    "status": "Pending",
    "bank_name": "BIDV",
    "account_holder_name": "TRAN THI B",
    "account_number": "1234567890",
    "expired_at": "2025-12-19 08:15:00",
    "qr_code": "data:image/png;base64,...",
    "qr_code_url": "https://qr.sepay.vn/img?acc=..."
  }
}

Errors

HTTP	error_code	Description
400	-	BIDV: Bank account is not an enterprise account
400	-	Sacombank: Merchant not activated for this account
400	-	Sacombank: `va_prefix` is invalid or not activated
409	`duplicate`	Duplicate `order_code`
422	`validation_error`	Validation error