Bắt đầu nhanh

Hướng dẫn tạo đơn hàng VA, nhận thanh toán qua webhook. Hỗ trợ BIDV và Sacombank.

Tạo số VA riêng cho mỗi đơn hàng. Khách chuyển khoản vào VA, SePay tự động khớp và gửi webhook.

Ngân hàng hỗ trợ

BIDVSacombank
Loại tài khoảnDoanh nghiệpCá nhân / HKD
Tiền tố VA (va_prefix)Không cầnBắt buộc
Số tiền (amount)Tùy chọnBắt buộc
Thanh toán một phầnCóKhông (chỉ đúng số tiền)
Sacombank: chỉ nhận đúng số tiền

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

Trạng thái

Trạng thái đơn hàng
Rendering diagram...
Trạng thái VA
Rendering diagram...

Endpoints

GET
https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/orders
POST
https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/orders
GET
https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/orders/{order_xid}
DELETE
https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/orders/{order_xid}
POST
https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/orders/{order_xid}/va
DELETE
https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/orders/{order_xid}/va/{va_number}
GET
https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/prefixes
GET
https://userapi.sepay.vn/v2/bank-accounts/{ba_xid}/prefixes/{va_prefix}

Luồng thanh toán qua VA

Luồng tích hợp đơn hàng VA
Rendering diagram...

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

Chuẩn bị

  • Tạo API Token
  • Tài khoản ngân hàng đã liên kết trên SePay:
    • BIDV: tài khoản doanh nghiệp
    • Sacombank: tài khoản cá nhân hoặc hộ kinh doanh, merchant đã kích hoạt
  • Lấy UUID tài khoản từ API Tài khoản ngân hàng

Lấy tiền tố VA (chỉ Sacombank)

BIDV

BIDV không cần bước này. Bỏ qua và chuyển sang bước tiếp theo.

Mỗi đơn hàng Sacombank phải có va_prefix. Gọi API lấy danh sách prefix:

Bash
1
2
curl -X GET "https://userapi.sepay.vn/v2/bank-accounts/{ba_uuid}/prefixes" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
200 OK
{
  "status": "success",
  "data": [
    {
      "va_prefix": "SEP200001WEB",
      "store_id": "WEB",
      "store_name": "NGUYEN VAN A",
      "status": "active",
      "created_at": "2026-03-20 09:00:00"
    }
  ]
}

Xem chi tiết Tiền tố VA

Tạo đơn hàng

cURL
1
2
3
4
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"}'
Response 201
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "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://qr.sepay.vn/img?acc=963NQDORD1234567890AB&bank=BIDV&amount=500000&template=compact"
  }
}

Hiển thị cho khách hàng

Từ response, hiển thị cho khách hàng:

  • Số tài khoản: va_number (số VA để chuyển khoản)
  • Số tiền: amount
  • Mã QR: qr_code hoặc qr_code_url
  • Thời hạn: expired_at (nếu có)

Nhận thông báo thanh toán

Khi khách hàng chuyển khoản thành công, SePay gửi webhook đến URL bạn đã cấu hình. Giao dịch sẽ chứa trường code khớp với order_code của đơn hàng.

Xem chi tiết cấu hình webhook.

Kiểm tra trạng thái đơn hàng

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

Trạng thái đơn hàng:

  • Pending: chờ thanh toán
  • Paid: đã thanh toán
  • Partially: thanh toán một phần (chỉ BIDV)
  • Cancelled: đã hủy

Tham số chính

Tham sốBắt buộcMô tả
va_prefixCó (Sacombank)Tiền tố VA. Không dùng cho BIDV.
order_codeKhôngMã đơn hàng (6-50 ký tự). Tự sinh nếu bỏ qua.
amountCó (Sacombank)Số tiền (VND). BIDV: tùy chọn.

Xem đầy đủ tham số

Thanh toán nhiều lần (chỉ BIDV)

BIDV hỗ trợ tạo thêm VA cho đơn hàng đang Pending hoặc Partially. Khi tất cả VA được thanh toán, đơn hàng chuyển sang Paid. Sacombank không hỗ trợ tính năng này.

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

Trước
—
Tiếp theo
—