API VA theo Đơn hàng cho BIDV doanh nghiệp
API VA (Virtual Account) theo đơn hàng là giải pháp tự động hóa xác nhận thanh toán cho ngân hàng BIDV tài khoản doanh nghiệp. Thay vì sử dụng một VA cố định, mỗi đơn hàng sẽ được cấp một VA riêng với số tiền khớp chính xác.
Giải thích luồng hoạt động
Khi khách hàng thực hiện thanh toán qua VA (Virtual Account), toàn bộ quá trình được xử lý tự động theo các bước sau:
- Sau khi khách hàng hoàn tất đơn hàng trên website của bạn, hệ thống sẽ tự động kết nối với SePay thông qua API để tạo một đơn hàng mới. SePay sẽ trả về một số VA duy nhất cho đơn hàng này.
- Website của bạn ngay lập tức hiển thị thông tin thanh toán cho khách hàng, bao gồm:
- Số tài khoản VA cần chuyển khoản
- Số tiền cần thanh toán chính xác
- Thời gian VA có hiệu lực
- Mã QR để quét thanh toán nhanh
- Khách hàng có thể dễ dàng thanh toán bằng cách quét mã QR hoặc chuyển khoản trực tiếp đến số VA được cấp.
- Ngay khi giao dịch được thực hiện thành công, ngân hàng sẽ tự động gửi thông báo đến SePay để xác nhận thanh toán.
- SePay nhận được thông báo và ngay lập tức chuyển tiếp thông tin này đến website của bạn thông qua Webhook
- Hệ thống của bạn xử lý thông tin nhận được, cập nhật trạng thái đơn hàng và hiển thị thông báo xác nhận thanh toán thành công cho khách hàng.
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:
- Lấy danh sách đơn hàng
- Tạo đơn hàng mới
- Lấy thông tin chi tiết đơn hàng
- Tạo thêm VA cho đơn hàng
- Hủy đơn hàng
- Hủy VA của đơn hàng
Bắt đầu
URL của API:
https://my.sepay.vn/userapi/bidv/{bank_account_id}
Để 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.
Lấy danh sách đơn hàng
/orders
Lấy danh sách các đơn hàng đã được tạo với phân trang.
Ví dụ:
GET https://my.sepay.vn/userapi/bidv/123456/orders
Authorization: Bearer {token}
HTTP/1.1 200 OK
Content-Type: application/json
{
"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",
"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
/orders
Tạo một đơn hàng mới.
Thuộc tính | Mô tả | Kiểu | Bắt buộc |
---|---|---|---|
amount | Số tiền đơn hàng | number | Có |
order_code | Mã đơn hàng | string | Không |
duration | Thời gian sống của đơn hàng (tính bằng giây) | number | Không |
with_qrcode | Yêu cầu tạo QR Code | boolean | Không |
Ví dụ:
POST https://my.sepay.vn/userapi/bidv/123456/orders
Authorization: Bearer {token}
Content-Type: application/json
{
"amount": 100000,
"order_code": "ORD123456789",
"duration": 300,
"with_qrcode": true
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "success",
"message": "Order created successfully",
"data": {
"order_id": "f23cc0fe-c343-11ef-9c27-52c7e9b4f41b",
"order_code": "ORD123456789",
"va_number": "963NQDORDZVTBPJ3Z7H",
"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
/orders/{order_id}
Lấy thông tin chi tiết của một đơn hàng theo ID.
Ví dụ:
GET https://my.sepay.vn/userapi/bidv/123456/orders/b64247d3-c343-11ef-9c27-52c7e9b4f41b
Authorization: Bearer {token}
HTTP/1.1 200 OK
Content-Type: application/json
{
"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",
"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
/orders/{order_id}/va
Tạo thêm một VA mới cho đơn hàng đã tồn tại.
Thuộc tính | Mô tả | Kiểu | Bắt buộc |
---|---|---|---|
amount | Số tiền của VA (tối đa bằng số tiền của đơn hàng) | number | Có |
duration | Thời gian sống của VA (tính bằng giây) | number | Không |
Ví dụ:
POST https://my.sepay.vn/userapi/bidv/123456/orders/b64247d3-c343-11ef-9c27-52c7e9b4f41b/va
Authorization: Bearer {token}
Content-Type: application/json
{
"amount": 100000,
"duration": 300
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "success",
"message": "VA created successfully",
"data": {
"va_number": "963NQDORD8DTYFPW5MV",
"amount": 2000,
"status": "Unpaid",
"expired_at": "2024-12-26 11:55:55"
}
}
Hủy đơn hàng
/orders/{order_id}
Hủy đơn hàng.
Ví dụ:
DELETE https://my.sepay.vn/userapi/bidv/123456/orders/b64247d3-c343-11ef-9c27-52c7e9b4f41b
Authorization: Bearer {token}
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "success",
"message": "Order cancelled successfully",
"data": {
"status": "Cancelled"
}
}
Hủy VA
/orders/{order_id}/va/{va_number}
Hủy một VA.
Ví dụ:
DELETE https://my.sepay.vn/userapi/bidv/123456/orders/b64247d3-c343-11ef-9c27-52c7e9b4f41b/va/963NQDORD8DTYFPW5MV
Authorization: Bearer {token}
HTTP/1.1 200 OK
Content-Type: application/json
{
"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", // Mã đơn hàng của VA
"transferAmount": 2277000, // Số tiền giao dịch
"transferType": "in", // Loại giao dịch (in: tiền vào)
...
}
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 | Mô tả |
---|---|
Pending | Đơn hàng chưa thanh toán |
Paid | Đơn hàng đã thanh toán |
Cancelled | Đơn hàng đã bị hủy |
Trạng thái VA
Trạng thái | Mô tả |
---|---|
Unpaid | VA chưa thanh toán |
Paid | VA đã thanh toán |
Cancelled | VA đã bị hủy |
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
SePay sẽ trả về các mã lỗi sau:
Mã lỗi | Mô tả |
---|---|
400 | Bad Request - Tham số không hợp lệ hoặc thiếu |
401 | Unauthorized - Token không hợp lệ |
404 | Not Found - Không tìm thấy tài nguyên |
429 | Too Many Requests - Vượt quá giới hạn request |