Tổng quan API và xác thực Bank Hub

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ử

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.

Authorization: Basic {base64(client_id:client_secret)}

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: Bearer YOUR_ACCESS_TOKEN

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:

{
  "code": 400,
  "message": "Bad request",
  "errors": {
    "field_name": "Thông báo lỗi chi tiết"
  }
}

{
  "code": 401,
  "message": "Unauthenticated"
}

{
  "code": 404,
  "message": "Resource not found"
}

Danh sách API Endpoints

• Link Token APIs:

• Company APIs:

• Bank Account APIs:

• Transaction APIs:

• Merchant Config APIs:

• Webhook APIs:

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