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

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

POST

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

Tham số

ba_xidstringrequired

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

tidstringrequired (Vietcombank)

Terminal ID Vietcombank (bắt buộc khi tài khoản là Vietcombank). Lấy từ endpoint GET /bank-accounts/{ba_xid}/terminals. Là Terminal ID gốc Vietcombank cấp, không phải xid UUID của SePay.

va_prefixstringrequired (Sacombank)

Tiền tố VA (bắt buộc khi tài khoản là Sacombank). Ví dụ SEP200001WEB. Không dùng cho BIDV và Vietcombank.

order_codestring

Mã đơn hàng (alphanumeric, 6-50 ký tự). Tự sinh nếu để trống. Vietcombank giới hạn tối đa 15 ký tự.

amountintegerrequired (Sacombank, Vietcombank)

Số tiền (số nguyên dương, tối đa 12 chữ số). Bắt buộc khi tài khoản là Sacombank hoặc Vietcombank (chỉ nhận đúng số tiền). Tùy chọn với BIDV.

va_holder_namestring

Tên chủ VA. Chỉ áp dụng cho tài khoản BIDV doanh nghiệp (liên hệ SePay để bật tính năng tùy chỉnh tên VA). Chữ hoa A-Z, số 0-9, khoảng trắng. Sacombank và Vietcombank không hỗ trợ.

durationinteger

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

with_qrcodeenum

Bao gồm mã QR trong response (0 hoặc 1)

qrcode_templateenum

Mẫu mã QR

Khác biệt theo ngân hàng

Tham số	BIDV	Sacombank	Vietcombank
`tid`	Không cần	Không cần	Bắt buộc. Xem Danh sách terminal.
`va_prefix`	Không cần	Bắt buộc. Xem Tiền tố VA.	Không cần
`amount`	Tùy chọn	Bắt buộc (chỉ nhận đúng số tiền)	Bắt buộc (chỉ nhận đúng số tiền)
`order_code`	6–50 ký tự	6–50 ký tự	6–15 ký tự
`va_holder_name`	Chỉ BIDV doanh nghiệp (cần bật tính năng, liên hệ SePay)	Không hỗ trợ	Không hỗ trợ

Sacombank và Vietcombank: chỉ nhận đúng số tiền

Sacombank và Vietcombank không hỗ trợ thanh toán một phần. Đơn hàng chỉ chuyển Pending sang Paid hoặc Cancelled.

Tham số `tid` của Vietcombank

tid phải là Terminal ID gốc do Vietcombank cấp (ví dụ 20933557), không phải xid UUID của SePay. Lấy tid hợp lệ qua Danh sách terminal trước khi tạo đơn hàng; nếu chưa có terminal, xem cách thêm terminal cho tài khoản Vietcombank doanh nghiệp/hộ kinh doanh. Nếu gửi nhầm UUID, SePay trả 422 invalid_tid_format. Nếu tid không thuộc tài khoản ngân hàng, SePay trả 422 invalid_tid.

Code mẫu

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 '{"tid":"string","va_prefix":"string","order_code":"string","amount":0,"va_holder_name":"string","duration":0,"with_qrcode":"0","qrcode_template":"compact"}'

Response (HTTP 201)

Response 201 - Tạo đơn hàng thành công

{
  "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": null,
    "qr_code": "data:image/png;base64,...",
    "qr_code_url": "https://qr.sepay.vn/img?acc=963NQDORD1234567890AB&bank=BIDV&amount=1000000&template=compact"
  }
}

statusstring

messagestring

dataobject

Lỗi

HTTP	error_code	Mô tả
400	-	BIDV: Tài khoản không phải loại doanh nghiệp
400	-	Sacombank: Merchant chưa được kích hoạt
400	-	Sacombank: `va_prefix` không tồn tại hoặc đã bị hủy
409	`duplicate`	Trùng `order_code`
422	`validation_error`	Lỗi validation
422	`invalid_tid_format`	Vietcombank: `tid` đang gửi UUID `xid` thay vì Terminal ID gốc
422	`invalid_tid`	Vietcombank: `tid` không thuộc tài khoản ngân hàng này
500	`vcb_error`	Vietcombank: lỗi không xác định khi tạo đơn hàng. 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.