Tổng quan API

Tổng quan về hệ thống API của SePay Bank Hub, bao gồm môi trường, xác thực, HTTP status code, định dạng error và danh sách endpoints.

Giới thiệu

Ngoài Hosted Link, Bank Hub cung cấp bộ API RESTful đầy đủ để:

  • Tạo và quản lý link token
  • Tạo và Quản lý công ty
  • Quản lý tài khoản ngân hàng đã liên kết
  • Truy vấn lịch sử giao dịch
  • Cấu hình merchant
  • Cấu hình webhook nhận sự kiện

Môi trường API & Versioning

Bank Hub hỗ trợ 2 môi trường:

Production

  • Base URL: https://bankhub-api.sepay.vn
  • API Version: /v1
  • Sử dụng cho môi trường thực tế

Sandbox

  • Base URL: https://bankhub-api-sandbox.sepay.vn
  • API Version: /v1
  • Sử dụng cho phát triển và kiểm thử
Lưu ý

Tất cả endpoint đều có tiền tố /v1/ và được định tuyến dựa trên hostname.

Xác thực API

Tạo Access Token

Endpoint tạo token sử dụng Basic Authentication với client_id và client_secret được SePay cấp.

POST
/v1/token
Authorization: Basic {base64(client_id:client_secret)}
Bảo mật

KHÔNG sử dụng API này từ client-side (browser, mobile app). API tạo token yêu cầu client_secret - thông tin này phải được bảo mật tuyệt đối trên server. Chỉ gọi API này từ backend server của bạn.

Chi tiết về API tạo token xem tại: API Tạo Token

Gọi API nghiệp vụ

Tất cả API nghiệp vụ khác yêu cầu xác thực bằng Bearer Token:

Authorization Header
Authorization: Bearer YOUR_ACCESS_TOKEN
Quản lý Token
  • Token có thời gian hiệu lực giới hạn (TTL)
  • Khi token hết hạn, API sẽ trả về lỗi 401 Unauthorized
  • Cần gọi lại API /v1/token để lấy token mới
  • Gợi ý: Nên implement cơ chế refresh token tự động trước khi hết hạn

HTTP Status Code

Bank Hub sử dụng các HTTP status code chuẩn:

  • 200 OK – Request thành công
  • 201 Created – Tạo resource thành công
  • 400 Bad Request – Lỗi validation hoặc request không hợp lệ
  • 401 Unauthorized – Thiếu hoặc sai thông tin xác thực
  • 404 Not Found – Không tìm thấy resource
  • 405 Method Not Allowed – Sai HTTP method
  • 500 Internal Server Error – Lỗi hệ thống
  • 503 Service Unavailable – Dịch vụ tạm thời không khả dụng

Định dạng Error Response

Tất cả lỗi API đều trả về theo cấu trúc thống nhất:

RESPONSE 400 - Validation Error
{
  "code": 400,
  "message": "Bad request",
  "errors": {
    "field_name": "Thông báo lỗi chi tiết"
  }
}
RESPONSE 401 - Authentication Error
{
  "code": 401,
  "message": "Unauthenticated"
}
RESPONSE 404 - Not Found
{
  "code": 404,
  "message": "Resource not found"
}

Danh sách API Endpoints

  • Link Token APIs:
POST
/v1/link-token/create

Tạo link liên kết hoặc huỷ liên kết ngân hàng (có thể dùng link để nhúng Iframe hoặc dùng cho SDK). Chi tiết API →

POST
/v1/link-token/get

Lấy thông tin chi tiết của link token đã tạo. Chi tiết API →

POST
/v1/link-token/revoke

Huỷ bỏ link token đã tạo, vô hiệu hoá link. Chi tiết API →

  • Company APIs:
GET
/v1/company

Lấy danh sách công ty của merchant. Chi tiết API →

GET
/v1/company/{xid}

Lấy thông tin chi tiết của một công ty theo xid. Chi tiết API →

POST
/v1/company/create

Tạo công ty mới cho merchant. Chi tiết API →

POST
/v1/company/edit/{xid}

Cập nhật thông tin công ty theo xid. Chi tiết API →

GET
/v1/company/counter/{xid}

Đếm giao dịch của công ty. Chi tiết API →

  • Bank Account APIs:
GET
/v1/bank-account

Lấy danh sách tài khoản ngân hàng đã liên kết. Chi tiết API →

GET
/v1/bank-account/{xid}

Lấy thông tin chi tiết của một tài khoản ngân hàng theo xid. Chi tiết API →

  • Transaction APIs:
GET
/v1/transaction

Truy vấn lịch sử giao dịch với bộ lọc linh hoạt. Chi tiết API →

GET
/v1/transaction/{transaction_id}

Lấy thông tin chi tiết của một giao dịch theo transaction_id. Chi tiết API →

  • Merchant Config APIs:
GET
/v1/merchant-config

Lấy cấu hình hiển thị của merchant (logo, tên, màu sắc). Chi tiết API →

POST
/v1/merchant-config

Cập nhật cấu hình hiển thị của merchant. Chi tiết API →

POST
/v1/merchant-config/logo

Upload logo cho merchant. Chi tiết API →

  • Webhook APIs:
GET
/v1/webhook

Lấy cấu hình webhook hiện tại. Chi tiết API →

POST
/v1/webhook

Cấu hình URL và secret key cho webhook nhận sự kiện. Chi tiết API →

Best Practices

1. Quản lý Token

  • Lưu trữ token an toàn, không để lộ ra client-side
  • Implement cơ chế refresh token tự động trước khi hết hạn
  • Xử lý lỗi 401 bằng cách tự động lấy token mới và retry request

2. Xử lý Lỗi

  • Luôn kiểm tra HTTP status code
  • Parse và hiển thị thông báo lỗi từ response
  • Implement retry logic cho các lỗi tạm thời (5xx)

3. Rate Limiting

  • Tuân thủ rate limit của API
  • Implement exponential backoff khi gặp lỗi 429
  • Cache dữ liệu khi có thể để giảm số lượng API calls

4. Idempotency

  • Sử dụng idempotency key cho các request quan trọng
  • Lưu trữ và kiểm tra response dựa trên idempotency key
  • Xử lý duplicate requests một cách an toàn

Bước tiếp theo

Để bắt đầu sử dụng Bank Hub API, bạn có thể thực hiện theo thứ tự sau:

  1. Tạo Access Token - Lấy Bearer token để xác thực các API tiếp theo
  2. Tạo công ty - Tạo công ty để quản lý tài khoản ngân hàng
  3. Tạo Link Token - Tạo link để người dùng liên kết ngân hàng
Gợi ý

Xem Bắt đầu nhanh để có hướng dẫn tích hợp từng bước với code mẫu đầy đủ.

Trước
—
Tiếp theo
—