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.
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_idcủ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.
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
amountnhỏ hơn số tiền đơn hàng khi tạo VA mới - Đặt
amountlà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
- Thiết lập
-
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
Paidvà 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
GET
/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",
"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
POST
/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, set là null để đơn hàng không hạn chế số tiền thanh toán | number hoặc null | Có |
| order_code | Mã đơn hàng | string | Không |
| duration |
Thời gian hiệu lực của đơn hàng (tính bằng giây), set là null để đơn hàng không hạn chế thời gian thanh toán - Mặc định là 600 giây (10 phút) - Tối đa là 31536000 giây (1 năm) |
number hoặc null | Không |
| va_holder_name | Tên chủ tài khoản VA (chỉ chấp nhận chữ in hoa, số và khoảng trắng, tối đa 70 ký tự) | string | Không |
| with_qrcode | Yêu cầu tạo QR Code | boolean | Không |
Lưu ý: Tham số
va_holder_name chỉ hỗ trợ cho các tài khoản BIDV doanh nghiệp được SePay bật tính năng custom tên hiển thị. Vui lòng liên hệ hỗ trợ bên SePay để được bật tính năng này.
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",
"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
GET
/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",
"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
POST
/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: - Mặc định bằng số tiền của đơn hàng - Có thể thiết lập nhỏ hơn số tiền đơn hàng để cho phép thanh toán từng phần - Đặt null để VA có thể nhận nhiều lần thanh toán đến khi đủ số tiền đơn hàng
|
number hoặc null | Có |
| va_holder_name | Tên chủ tài khoản VA (chỉ chấp nhận chữ in hoa, số và khoảng trắng, tối đa 70 ký tự) | string | Không |
| duration |
Thời gian hiệu lực của VA (tính bằng giây), set là null để đơn hàng không hạn chế thời gian thanh toán
- Mặc định là 600 giây (10 phút) - Tối đa là 31536000 giây (1 năm) |
number hoặc null | 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,
"va_holder_name": "NGO QUOC DAT",
"duration": 300
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "success",
"message": "VA created successfully",
"data": {
"va_number": "963NQDORD8DTYFPW5MV",
"va_holder_name": "NGO QUOC DAT",
"amount": 2000,
"status": "Unpaid",
"expired_at": "2024-12-26 11:55:55"
}
}
Hủy đơn hàng
DELETE
/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
DELETE
/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 |
| Partially | Đơn hàng đã thanh toán một phầ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-Afterchỉ 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 |
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
amountlànullđể đơn hàng và VA không hạn chế số lần thanh toán - Đặt
durationlànullđể đơn hàng không hạn chế thời gian thanh toán
Ví dụ:
POST https://my.sepay.vn/userapi/bidv/123456/orders
Authorization: Bearer {token}
Content-Type: application/json
{
"amount": null,
"duration": null
}
Khi đơn hàng được tạo, bạn có thể tạo VA mới cho đơn hàng bằng cách gọi API Tạo thêm VA.
