API tạo VA cho đơn hàng

Tạo VA mới cho đơn hàng

POST

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

Trạng thái đơn hàng cho phép

Đơn hàng phải ở trạng thái Pending, hoặc Partially (chỉ BIDV).

BIDV: chỉ BIDV chuyển đơn hàng sang Partially khi tổng số tiền nhận chưa đủ amount. Các VA bổ sung có thể tích lũy tới khi đủ amount thì đơn hàng chuyển Paid.
Sacombank và Vietcombank: đơn hàng chuyển trực tiếp Pending → Paid ngay khi nhận thanh toán đầu tiên. Các VA bổ sung dùng để cung cấp nhiều kênh thanh toán song song, VA nào được thanh toán trước sẽ đóng đơn hàng.

Tham số

ba_xidstringrequired

UUID tài khoản ngân hàng

order_xidstringrequired

UUID đơn hàng

amountinteger

Số tiền, không được vượt quá số tiền đơn hàng

va_holder_namestring

Tên chủ VA. Bắt buộc nếu đã bật tính năng tùy chỉnh tên VA.

durationinteger

Thời hạn VA tính bằng giây

Mặc định `amount` của VA bổ sung

VA bổ sung trên Sacombank và Vietcombank: nếu bỏ trống amount, hệ thống mặc định bằng amount của đơn hàng gốc — VA bổ sung trên các ngân hàng này thực chất là một kênh thanh toán lặp lại cho cùng số tiền, không phải thu phần còn lại.

VA bổ sung Vietcombank còn kế thừa tid từ đơn hàng gốc, không cần truyền lại.

Code mẫu

curl --request POST \
  --url https://userapi.sepay.vn/v2/bank-accounts/f9e8d7c6-b5a4-3210-fedc-ba0987654321/orders/b2c3d4e5-f6a7-8901-bcde-f12345678902/va \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"amount":0,"va_holder_name":"string","duration":0}'

Response (HTTP 201)

Response 201 - Tạo VA thành công

{
  "status": "success",
  "message": "VA created successfully",
  "data": {
    "va_number": "963NQDORD1234567890CD",
    "va_holder_name": "TRAN THI B",
    "amount": 500000,
    "status": "Unpaid",
    "expired_at": "2025-12-19 08:15:00"
  }
}

statusstring

messagestring

dataobject

Lỗi

HTTP	error_code	Mô tả
422	`invalid_state`	Trạng thái đơn hàng không cho phép tạo thêm VA (chỉ tạo được cho `Pending`, hoặc `Partially` với BIDV)
500	`vcb_error`	Vietcombank: lỗi không xác định khi tạo VA. Liên hệ SePay.
503	`vcb_connection_error`	Vietcombank: dịch vụ tạm thời gián đoạn. Vui lòng thử lại sau ít phút.