Bắt đầu nhanh API VA theo đơn hàng

VA theo đơn hàng là số tài khoản ảo riêng cho từng đơn hàng. Khách chuyển khoản vào VA đó, SePay khớp giao dịch với đơn hàng theo đúng số tiền và gửi webhook về hệ thống của bạn.

Ngân hàng hỗ trợ

Tài khoản BIDV, Sacombank, Vietcombank và VietinBank đã liên kết trên SePay đều tạo được đơn hàng VA qua cùng một endpoint, nhưng khác nhau ở loại tài khoản, tham số bắt buộc và cách nhận tiền. Đọc phần của ngân hàng bạn đang tích hợp.

BIDV

Khách trả chưa đủ amount thì đơn hàng chuyển Partially và VA vẫn nhận tiếp cho tới khi đủ.

Tài khoản BIDV doanh nghiệp có thể đặt tên chủ VA riêng qua va_holder_name, nhưng cần bật tính năng trước. Liên hệ SePay nếu bạn cần.

Sacombank

Mỗi đơn hàng Sacombank phải gắn với một tiền tố VA. Gọi Tiền tố VA để lấy va_prefix đang hoạt động trước khi tạo đơn hàng. Merchant phải được kích hoạt, nếu chưa thì lệnh tạo trả 400.

Vietcombank

VietinBank

Đơn hàng VietinBank luôn phải có amount, nhưng khách trả thiếu vẫn được ghi nhận: đơn hàng chuyển Partially và VA tiếp tục nhận cho tới khi đủ. VA đã hết hạn, đã thanh toán hoặc đã hủy không nhận thêm tiền.

Giao dịch lớn hơn amount của VA không được khớp: tiền vẫn vào tài khoản thật nhưng đơn hàng không chuyển sang Paid. Thu nhiều đợt trên VietinBank thì mỗi đợt phải nhỏ hơn hoặc bằng số tiền của VA.

Khoản đã thu trên VietinBank có thể hoàn tiền qua API.

Trạng thái

Đơn hàng còn mang trường refund_status riêng, null cho tới khi có lệnh hoàn tiền đầu tiên. Trường này chỉ đổi giá trị trên ngân hàng có hỗ trợ hoàn tiền.

Khác status, trường này tính lại từ toàn bộ lệnh hoàn của đơn hàng nên lùi được. Xem ý nghĩa từng giá trị.

Các endpoint

Luồng xác thực thanh toán qua VA theo đơn hàng

order_code là sợi dây nối đơn hàng bên bạn với đơn hàng trên SePay. Website tự sinh mã khi khách đặt hàng, truyền vào lệnh tạo đơn hàng, rồi webhook trả mã đó lại trong trường code để bạn đối chiếu. Bỏ trống thì SePay tự sinh, nhưng khi đó bạn phải tự lưu mã trả về để khớp ngược.

SePay chuẩn hoá order_code về chữ in hoa trước khi lưu. Gửi dh20250001 vẫn hợp lệ nhưng đơn hàng được lưu là DH20250001, và đó cũng là giá trị mà response và webhook trả về. Nếu hệ thống bạn dùng mã có chữ thường, hãy so khớp không phân biệt hoa thường, hoặc lưu lại đúng giá trị trong response thay vì giá trị bạn đã gửi.

Luồng hoàn tiền

Khi đơn hàng đã Paid hoặc Partially, bạn trả lại phần đã thu bằng API hoàn tiền. Hiện chỉ tài khoản VietinBank doanh nghiệp đã được SePay bật hoàn tiền mới dùng được.

Hoàn tiền không đổi status hay paid_amount của đơn hàng; thay vào đó đơn hàng mang thêm trường refund_status. Xem Hoàn tiền theo đơn hàng để biết tham số, sơ đồ trạng thái và bảng lỗi.

Các bước tích hợp

curl -X POST "https://userapi.sepay.vn/v2/bank-accounts/{ba_uuid}/orders" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{"amount": 500000, "order_code": "DH20250001", "with_qrcode": "1"}'

{
  "status": "success",
  "message": "Order created successfully",
  "data": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678902",
    "order_code": "DH20250001",
    "va_number": "963NQDORD1234567890AB",
    "va_holder_name": "CONG TY CP TECH VINA",
    "amount": 500000,
    "status": "Pending",
    "bank_name": "BIDV",
    "account_holder_name": "CONG TY CP TECH VINA",
    "account_number": "1234567890",
    "expired_at": null,
    "qr_code": "data:image/png;base64,...",
    "qr_code_url": "https://vietqr.app/img?acc=963NQDORD1234567890AB&bank=BIDV&amount=500000&template=compact"
  }
}

curl -X GET "https://userapi.sepay.vn/v2/bank-accounts/{ba_uuid}/orders/{order_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Tham số chính

Xem đầy đủ tham số

Thanh toán một phần

Thanh toán một phần là khi khách chuyển ít hơn amount của đơn hàng mà SePay vẫn ghi nhận khoản đó, thay vì chỉ khớp khi số tiền đúng bằng amount. Đơn hàng thu dần qua nhiều lần chuyển khoản cho tới khi đủ.

Lần chuyển đầu chưa đủ amount đẩy đơn hàng sang Partially, trường paid_amount ghi tổng đã thu. VA vẫn nhận tiếp, mỗi lần chuyển cộng thêm vào paid_amount. Khi paid_amount đạt amount, đơn hàng chuyển Paid. Bạn cũng tạo thêm VA được cho đơn hàng đang Pending hoặc Partially để thu phần còn thiếu.

So với thanh toán toàn phần

Hỗ trợ theo ngân hàng

BIDV và VietinBank ghi nhận trả thiếu: đơn hàng dừng ở Partially cho tới khi thu đủ.

Riêng VietinBank có thêm một ràng buộc ở chiều ngược lại: giao dịch lớn hơn số tiền của VA không được khớp. Tiền vẫn vào tài khoản thật nhưng đơn hàng đứng nguyên. Nên khi thu làm nhiều đợt trên VietinBank, mỗi đợt phải nhỏ hơn hoặc bằng số tiền của VA.

Tạo thêm VA để thu nốt phần thiếu thì phải tự tính và truyền amount. Bỏ trống amount là VA lấy amount của đơn hàng gốc, không phải phần còn thiếu, kể cả trên BIDV. Với đơn hàng mở của BIDV (amount null) thì VA bổ sung mặc định amount bằng 0.

Sacombank và Vietcombank không hỗ trợ Partially: đơn hàng chuyển thẳng từ Pending sang Paid khi nhận thanh toán. Hai ngân hàng này vẫn tạo thêm VA được cho đơn hàng Pending, nhưng VA bổ sung là kênh thanh toán song song cho cùng số tiền, không phải để thu phần còn thiếu.

Xem API tạo VA

Hủy đơn hàng hoặc VA

Chỉ hủy được đơn hàng Pending và VA Unpaid. Response: 204 No Content.

Hủy đơn hàng | Hủy VA

Xem thêm

• Tạo đơn hàng (chi tiết API)
• Danh sách đơn hàng
• Hoàn tiền đơn hàng
• Tiền tố VA
• Danh sách terminal
• Cấu hình webhook