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_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.
  Payment method screen

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

GET

/userapi/bidv/123456/orders

Content-Type: application/json
Authorization: Bearer {token}

bash

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

POST

/userapi/bidv/123456/orders

Content-Type: application/json
Authorization: Bearer {token}

Tham số yêu cầu

Tên	Loại	Bắt buộc	Mô tả
`amount`	number/null	Bắt buộc	Số tiền đơn hàng, set là null để đơn hàng không hạn chế số tiền thanh toán.
`order_code`	string	Không bắt buộc	Mã đơn hàng.
`duration`	number/null	Không bắt buộc	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 giới hạn thời gian thanh toán. Mặc định là 600 giây (10 phút), tối đa là 31,536,000 giây (1 năm).
`va_holder_name`	string	Không bắt buộc	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ự).
`with_qrcode`	boolean	Không bắt buộc	Yêu cầu tạo QR Code.

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.

bash

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

GET

/userapi/bidv/123456/orders/{order_id}

Content-Type: application/json
Authorization: Bearer {token}

Lấy thông tin chi tiết của một đơn hàng theo ID.
Tham số đường dẫn
Tên Loại Bắt buộc Mô tả
order_id
string Bắt buộc
ID của một đơn hàng

bash

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

POST

/orders/{order_id}/va

Content-Type: application/json
Authorization: Bearer {token}

Tạo thêm một VA mới cho đơn hàng đã tồn tại.
Tham số đường dẫn

Tên	Loại	Bắt buộc	Mô tả
`order_id`	string	Bắt buộc	ID của một đơn hàng

Tham số yêu cầu

Tên	Loại	Bắt buộc	Mô tả
`amount`	number/null	Bắt buộc	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.
`va_holder_name`	string	Không bắt buộc	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ự).
`duration`	number/null	Không bắt buộc	Thời gian hiệu lực của VA (tính bằng giây). Set là null để VA 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à 31,536,000 giây (1 năm).

bash

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

DELETE

/orders/{order_id}

Content-Type: application/json
Authorization: Bearer {token}

Tham số đường dẫn

Tên	Loại	Bắt buộc	Mô tả
`order_id`	string	Bắt buộc	ID của một đơn hàng

Hủy VA

DELETE

/orders/{order_id}/va/{va_number}

Content-Type: application/json
Authorization: Bearer {token}

Tham số đường dẫn

Tên	Loại	Bắt buộc	Mô tả
`order_id`	string	Bắt buộc	ID của một đơn hàng
`va_number`	string	Bắt buộc	Số va

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:

RESPONSE

{
  "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 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

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	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ã HTTP	Mô tả	Nguyên nhân
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 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ụ:
bash
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.