API VA theo Đơn hàng cho BIDV doanh nghiệp

Bạn có thể làm gì với API này?

SePay cho phép bạn thực hiện những truy vấn sau với VA theo đơn hàng:

Bắt đầu

Để sử dụng API VA theo đơn hàng, bạn cần:

• Tạo một API Token để xác thực các yêu cầu API của bạn.
• Lấy bank_account_id của tài khoản BIDV doanh nghiệp từ API Tài khoản ngân hàng hoặc lấy trực tiếp từ giao diện quản lý tài khoản ngân hàng trên SePay.

Nhấn để phóng to

Thanh toán từng phần (Partially Payment)

SePay hỗ trợ thanh toán từng phần cho đơn hàng thông qua cơ chế Virtual Account (VA). Khi sử dụng chức năng này:

• Bạn có thể tạo đơn hàng với số tiền đầy đủ, nhưng cho phép khách hàng thanh toán theo nhiều đợt bằng cách:
  • Thiết lập amount nhỏ hơn số tiền đơn hàng khi tạo VA mới
  • Đặt amount là null để VA có thể nhận nhiều lần thanh toán với bất kỳ số tiền nào cho đến khi đạt tổng số tiền đơn hàng
• Khi khách hàng thanh toán một phần, trạng thái đơn hàng sẽ chuyển thành Partially
• Khi tổng số tiền thanh toán đạt đủ số tiền đơn hàng, trạng thái đơn hàng sẽ tự động chuyển thành Paid và VA sẽ không còn nhận thêm thanh toán

Tính năng này đặc biệt hữu ích cho các đơn hàng có giá trị lớn hoặc khi khách hàng cần thanh toán theo đợt.

Lấy danh sách đơn hàng

Code mẫu

curl --request GET \
  --url https://my.sepay.vn/userapi/bidv/123456/orders \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response

{
  "status": "success",
  "data": {
    "orders": [
      {
        "id": "b64247d3-c343-11ef-9c27-52c7e9b4f41b",
        "order_code": "ORD123456789",
        "amount": 2000,
        "paid_amount": 2000,
        "status": "Paid",
        "created_at": "2024-12-26 11:41:46",
        "bank_name": "BIDV",
        "account_number": "1234567890",
        "account_holder_name": "NGO QUOC DAT",
        "va": [
          {
            "va_number": "963NQDORDRSIKYXYPTZ",
            "va_holder_name": "NGO QUOC DAT",
            "amount": 2000,
            "status": "Paid",
            "expired_at": "2024-12-26 11:51:45",
            "paid_at": "2024-12-26 11:42:12"
          }
        ]
      }
    ],
    "pagination": {
      "total": 1,
      "per_page": 20,
      "current_page": 1,
      "last_page": 1
    }
  }
}

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

Tham số yêu cầu

Code mẫu

curl --request POST \
  --url https://my.sepay.vn/userapi/bidv/123456/orders \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"amount":1000000,"order_code":"ORDER123","duration":600,"va_holder_name":"NGUYEN VAN A","with_qrcode":true}'

Response

{
  "status": "success",
  "message": "Order created successfully",
  "data": {
    "order_id": "f23cc0fe-c343-11ef-9c27-52c7e9b4f41b",
    "order_code": "ORD123456789",
    "va_number": "963NQDORDZVTBPJ3Z7H",
    "va_holder_name": "NGO QUOC DAT",
    "amount": 2000,
    "status": "Pending",
    "bank_name": "BIDV",
    "account_holder_name": "NGO QUOC DAT",
    "account_number": "1234567890",
    "expired_at": "2024-12-26 11:53:26",
    "qr_code": "data:image/png;base64,...==",
    "qr_code_url": "https://qr.sepay.vn/img?acc=..."
  }
}

Chi tiết đơn hàng

Lấy thông tin chi tiết của một đơn hàng theo ID.

Tham số đường dẫn

Code mẫu

curl --request GET \
  --url https://my.sepay.vn/userapi/bidv/123456/orders/b64247d3-c343-11ef-9c27-52c7e9b4f41b \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response

{
  "status": "success",
  "data": {
    "id": "b64247d3-c343-11ef-9c27-52c7e9b4f41b",
    "order_code": "ORD123456789",
    "amount": 2000,
    "paid_amount": 2000,
    "status": "Paid",
    "created_at": "2024-12-26 11:41:46",
    "bank_name": "BIDV",
    "account_number": "1234567890",
    "account_holder_name": "NGO QUOC DAT",
    "va": [
      {
        "va_number": "963NQDORDRSIKYXYPTZ",
        "va_holder_name": "NGO QUOC DAT",
        "amount": 2000,
        "status": "Paid",
        "expired_at": "2024-12-26 11:51:45",
        "paid_at": "2024-12-26 11:42:12"
      }
    ]
  }
}

Tạo thêm VA

Tạo thêm một VA mới cho đơn hàng đã tồn tại.

Tham số đường dẫn

Tham số yêu cầu

Code mẫu

curl --request POST \
  --url https://my.sepay.vn/userapi/bidv/123456/orders/b64247d3-c343-11ef-9c27-52c7e9b4f41b/va \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"amount":500000,"va_holder_name":"NGUYEN VAN A","duration":600}'

Response

{
  "status": "success",
  "message": "VA created successfully",
  "data": {
    "va_number": "963NQDORD8DTYFPW5MV",
    "va_holder_name": "NGUYEN VAN A",
    "amount": 500000,
    "status": "Unpaid",
    "expired_at": "2024-12-26 11:55:55"
  }
}

Hủy đơn hàng

Tham số đường dẫn

Code mẫu

curl --request DELETE \
  --url https://my.sepay.vn/userapi/bidv/123456/orders/b64247d3-c343-11ef-9c27-52c7e9b4f41b \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response

{
  "status": "success",
  "message": "Order cancelled successfully",
  "data": {
    "status": "Cancelled"
  }
}

Hủy VA

Tham số đường dẫn

Code mẫu

curl --request DELETE \
  --url https://my.sepay.vn/userapi/bidv/123456/orders/b64247d3-c343-11ef-9c27-52c7e9b4f41b/va/963NQDORD8DTYFPW5MV \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response

{
  "status": "success",
  "message": "VA cancelled successfully",
  "data": {
    "status": "Cancelled"
  }
}

Xử lý Webhook thông báo thanh toán

Khi khách hàng thanh toán thành công vào VA của đơn hàng, SePay sẽ gửi webhook thông báo đến website của bạn. Dữ liệu webhook sẽ bao gồm trường code chứa mã đơn hàng của VA đó.

Ví dụ dữ liệu webhook khi VA được thanh toán:

{
  "id": 92704,
  "gateway": "BIDV",
  "transactionDate": "2024-01-07 14:02:37",
  "code": "ORD123456789",
  "transferAmount": 2277000,
  "transferType": "in"
}

Website của bạn cần kiểm tra trường code để xác định đơn hàng được thanh toán và cập nhật trạng thái phù hợp.

Chi tiết về cách thiết lập và xử lý webhook, bạn có thể tham khảo Hướng dẫn tích hợp WebHooks.

Định nghĩa trạng thái

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

Trạng thái VA

Giới hạn request

SePay giới hạn số lượng request API theo đơn hàng như sau:

• 2 request/giây cho mỗi IP
• Vượt quá giới hạn sẽ nhận response mã 429
• Header X-SePay-UserApi-Retry-After chỉ ra thời gian cần đợi trước khi thử lại

Mã lỗi

Tạo đơn hàng không giới hạn số tiền và thời gian

Bạn có thể tạo đơn hàng không giới hạn số tiền và thời gian thanh toán bằng cách:

• Đặt amount là null để đơn hàng và VA không hạn chế số lần thanh toán
• Đặt duration là null để đơn hàng không hạn chế thời gian thanh toán

Ví dụ:

curl -X POST "https://my.sepay.vn/userapi/bidv/123456/orders" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "amount": null,
  "duration": null
}'