API tạo Link Token

API Endpoint

POST

https://bankhub-api.sepay.vn/v1/link-token/create

Request Body

company_xidstringrequired

Company XID - công ty thực hiện liên kết/hủy liên kết

purposeenumrequired

Mục đích tạo link token

completion_redirect_uristring

URL chuyển hướng sau khi hoàn thành flow

is_mobile_appenum

Flow được mở từ mobile app (1) hay web (0)

Mặc định: 0

languageenum

Ngôn ngữ hiển thị giao diện

Mặc định: vi

bank_account_xidstring

Bank Account XID. Bắt buộc khi purpose = UNLINK_BANK_ACCOUNT

Headers

company_xidstringrequired

Company XID - công ty thực hiện liên kết/hủy liên kết

purposeenumrequired

Mục đích tạo link token

completion_redirect_uristring

URL chuyển hướng sau khi hoàn thành flow

is_mobile_appenum

Flow được mở từ mobile app (1) hay web (0)

Mặc định: 0

languageenum

Ngôn ngữ hiển thị giao diện

Mặc định: vi

bank_account_xidstring

Bank Account XID. Bắt buộc khi purpose = UNLINK_BANK_ACCOUNT

Lưu ý

API này yêu cầu Bearer Token trong header Authorization
Link token có thời gian hiệu lực giới hạn (xem trường expires_at)
Sử dụng hosted_link_url để mở WebView cho người dùng
Với purpose UNLINK_BANK_ACCOUNT, bắt buộc phải có bank_account_xid
Với purpose LINK_BANK_ACCOUNT, không cần truyền bank_account_xid
bank_account_xid có thể lấy từ danh sách ngân hàng đã liên kết API danh sách ngân hàng

Xử lý lỗi

400Validation Error

Dữ liệu đầu vào không hợp lệ (company_xid không tồn tại, purpose sai format, thiếu bank_account_xid khi UNLINK)

401Unauthorized

Access token không hợp lệ hoặc đã hết hạn

404Not Found

Công ty hoặc tài khoản ngân hàng không tồn tại

API Response

Response 201 - Tạo thành công

{
  "xid": "string",
  "hosted_link_url": "https://example.com",
  "link_token": "string",
  "expires_at": "string"
}

xidstring

ID duy nhất của link token

hosted_link_urlstring

URL WebView hoàn chỉnh để mở trong iframe hoặc SDK

link_tokenstring

Token duy nhất để xác thực

expires_atstring

Thời điểm hết hạn (yyyy-mm-dd HH:mm:ss)

Response 400 - Lỗi validation

{
  "code": 400,
  "message": "Validation error",
  "errors": null
}

Code mẫu

curl --request POST \
  --url https://bankhub-api.sepay.vn/v1/link-token/create \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"company_xid":"d0424f2d-8a2c-4d55-aeed-a5ad9955f6a2","purpose":"LINK_BANK_ACCOUNT","completion_redirect_uri":"http://example.com","is_mobile_app":0,"language":"vi","bank_account_xid":"52930e2b-c38b-4cd1-b2a2-9ddcdc603104"}'

Ví dụ sử dụng

JSTạo link token để liên kết tài khoản mới

curl --location 'https://bankhub-api.sepay.vn/v1/link-token/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data '{
  "company_xid": "d3dafd01-e06b-11f0-b29e-52c7e9b4f41b",
  "purpose": "LINK_BANK_ACCOUNT",
  "completion_redirect_uri": "https://yourapp.com/success"
}'

JSTạo link token để hủy liên kết tài khoản

curl --location 'https://bankhub-api.sepay.vn/v1/link-token/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data '{
  "company_xid": "d3dafd01-e06b-11f0-b29e-52c7e9b4f41b",
  "purpose": "UNLINK_BANK_ACCOUNT",
  "bank_account_xid": "f414b73c-eebe-11f0-b16e-52c7e9b4f41b",
  "completion_redirect_uri": "https://yourapp.com/unlinked"
}'

Lưu ý quan trọng

Expiration: Link token có thời gian hiệu lực giới hạn. Kiểm tra expires_at và tạo token mới nếu hết hạn
One-time Use: Link token chỉ sử dụng một lần. Sau khi hoàn thành (thành công hoặc thất bại), cần tạo token mới
Redirect URI: URL completion_redirect_uri phải là HTTPS trong production
Validation: Với purpose UNLINK_BANK_ACCOUNT, nếu thiếu bank_account_xid sẽ trả về lỗi 400

Gợi ý sử dụng

Backend tạo link token qua API này
Backend trả hosted_link_url cho frontend
Frontend mở WebView (iframe hoặc SDK) với URL
Người dùng hoàn tất liên kết/hủy liên kết trong WebView
Sau khi xong, người dùng được redirect về completion_redirect_uri (nếu có)
Backend nhận webhook notification về kết quả

Bước tiếp theo

Sau khi tạo link token thành công:

SDK JavaScript - Sử dụng SDK để mở Hosted Link và quản lý sự kiện
Webhook Events - Nhận thông báo khi liên kết thành công
Thông tin Link Token - Kiểm tra trạng thái link token
Danh sách tài khoản ngân hàng - Xem các tài khoản đã liên kết