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, Vietcombank và VietinBank.

order_codestring

Mã đơn hàng (alphanumeric, 6-50 ký tự). SePay chuẩn hoá về chữ in hoa, nên gửi chữ thường sẽ nhận lại bản in hoa. Tự sinh nếu để trống, mã tự sinh dài 10 ký tự in hoa. Vietcombank giới hạn tối đa 15 ký tự.

amountintegerrequired (Sacombank, Vietcombank, VietinBank)

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), và khi tài khoản là VietinBank (nhận trả thiếu, từ chối trả vượt). 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, Vietcombank và VietinBank 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	VietinBank
`tid`	Không cần	Không cần	Bắt buộc. Xem Danh sách terminal.	Không cần
`va_prefix`	Không cần	Bắt buộc. Xem Tiền tố VA.	Không cần	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)	Bắt buộc (nhận trả thiếu, từ chối trả vượt)
`order_code`	6-50 ký tự	6-50 ký tự	6-15 ký tự	6-50 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ợ	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.

VietinBank cần đăng ký dịch vụ thu hộ qua tài khoản định danh

Tài khoản VietinBank doanh nghiệp phải đăng ký dịch vụ thu hộ qua tài khoản định danh với VietinBank thì mới tạo được đơn hàng. Tài khoản chưa đăng ký nhận 422 vietinbank_va_order_not_enabled. Nếu bạn gặp lỗi này, vui lòng liên hệ SePay để được hỗ trợ.

Đơn hàng VietinBank bắt buộc có amount, nhưng chấp nhận trả thiếu: đơn hàng chuyển Partially và VA vẫn nhận tiếp tới khi đủ. Giao dịch lớn hơn amount không được khớp vào VA: tiền vẫn vào tài khoản thật nhưng đơn hàng không tự chuyển Paid.

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://vietqr.app/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
400	-	VietinBank: Tài khoản không phải loại doanh nghiệp
409	`duplicate`	Trùng `order_code`
422	`validation_error`	Lỗi validation
422	`vietinbank_va_order_not_enabled`	VietinBank: tài khoản chưa đăng ký dịch vụ thu hộ qua tài khoản định danh, hoặc SePay chưa mở tính năng này
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.