Bắt đầu nhanh

Hướng dẫn tích hợp Bank Hub vào ứng dụng của bạn trong vài bước đơn giản - từ tạo token, tạo link token đến nhúng iframe webview và nhận thông báo biến động số dư

  • Lấy access_token từ API /v1/token
  • Sử dụng access_token để tạo link token
  • Nhúng hosted_link_url vào iframe trên website
Trước khi bắt đầu

Đảm bảo bạn đã có:

  • client_id và client_secret do SePay cấp
  • company_xid (UUID của công ty đã được tạo trong hệ thống Bank Hub) - API tạo công ty
  • Backend server để gọi API (không gọi từ client-side vì lý do bảo mật)

Bước 1: Lấy Access Token

  • Đầu tiên, bạn cần lấy access_token để xác thực cho các API tiếp theo. API này sử dụng Basic Authentication với client_id và client_secret.
Bảo mật

KHÔNG gọi API này từ client-side (browser, mobile app). API 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.

  • API Endpoint
POST
https://bankhub-api-sandbox.sepay.vn/v1/token
Authorization: Basic {base64(client_id:client_secret)}
Content-Type: application/json
  • Code mẫu
php
  • Response
RESPONSE 201 - Thành công
{
  "code": 201,
  "access_token": "36483db493b10304eb3abc143b3593fa1473eb9b",
  "ttl": 60000
}
Lưu trữ Token
  • Lưu access_token vào cache (Redis, Memcached) hoặc session
  • Token có thời gian hiệu lực (ttl), nên implement cơ chế refresh tự động
  • Khi nhận lỗi 401 Unauthorized, tự động lấy token mới

Bước 2: Tạo Link Token

Sau khi có access_token, sử dụng nó để tạo link token. Link token sẽ cung cấp hosted_link_url - đây là URL bạn sẽ nhúng vào iframe.

  • API Endpoint
POST
https://bankhub-api-sandbox.sepay.vn/v1/link-token/create
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
  • Code mẫu
php
Note

Code mẫu trên chỉ ví dụ cho trường hợp tạo link token cho luồng liên kết tài khoản, nếu bạn cần tạo luồng huỷ liên kết thì nên truyền purpose là UNLINK_BANK_ACCOUNT và truyền thêm bank_account_xid

  • Response
RESPONSE 201 - Tạo thành công
{
  "xid": "850e8400-e29b-41d4-a716-446655440000",
  "hosted_link_url": "https://bankhub.sepay.vn/link/850e8400-e29b-41d4-a716-446655440000",
  "link_token": "950e8400-e29b-41d4-a716-446655440000",
  "expires_at": "2024-01-17 10:30:00"
}

Bước 3: Nhúng Iframe vào Website

Sau khi có hosted_link_url từ bước 2, bạn có thể nhúng nó vào website thông qua iframe.

Thông tin

Nếu bạn đã cung cấp completion_redirect_uri khi tạo link token, bạn sẽ được redirect về URL đã cung cấp

PostMessage Events

Iframe sẽ gửi các sự kiện qua window.postMessage với format:

event format
{
  "event": "FINISHED_BANK_ACCOUNT_LINK | FINISHED_BANK_ACCOUNT_UNLINK | BANKHUB_CLOSE_LINK | BANKHUB_TOKEN_EXPIRED | BANKHUB_SESSION_EXPIRED",
  "metadata": {
    "account_number": "string",
    "account_type": "individual | enterprise"
  },
  "timestamp": "string"
}

Các loại events:

FINISHED_BANK_ACCOUNT_LINK

Tài khoản ngân hàng đã được liên kết thành công. Metadata chứa thông tin tài khoản.

FINISHED_BANK_ACCOUNT_UNLINK

Tài khoản ngân hàng đã được hủy liên kết thành công.

BANKHUB_CLOSE_LINK

Người dùng đóng/hủy bỏ flow liên kết.

BANKHUB_TOKEN_EXPIRED

Link token đã hết hạn, cần tạo token mới.

BANKHUB_SESSION_EXPIRED

Phiên làm việc đã hết hạn, cần khởi tạo lại.

Cấu hình nhận thông báo biến động số dư (IPN)

➤ Bạn có thể xem chi tiết tại đây

Trước
—
Tiếp theo
—