API tạo Link Token

POST /link-token/create — tạo Link Token một lần để mở WebView SePay Bank Hub cho luồng liên kết hoặc hủy liên kết tài khoản với redirect URI tùy biến.

||

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:

• LINK_BANK_ACCOUNT: liên kết tài khoản mới

• UNLINK_BANK_ACCOUNT: hủy liên kết (vô hiệu hóa) tài khoản

• REACTIVATE_BANK_ACCOUNT: khôi phục tài khoản đã bị vô hiệu hóa trong Bank Hub

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 hoặc REACTIVATE_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 REACTIVATE_BANK_ACCOUNT, bắt buộc phải có bank_account_xid; tài khoản phải đang thuộc diện khôi phục (đã bị ngừng kích hoạt qua luồng hủy liên kết trước đó)
  • 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 hoặc REACTIVATE, tài khoản không thuộc diện khôi phục)

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
1
2
3
4
5
6
7
8
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
1
2
3
4
5
6
7
8
9
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"
}'
JSTạo link token để khôi phục tài khoản ngừng kích hoạt
1
2
3
4
5
6
7
8
9
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": "REACTIVATE_BANK_ACCOUNT",
  "bank_account_xid": "f414b73c-eebe-11f0-b16e-52c7e9b4f41b",
  "completion_redirect_uri": "https://yourapp.com/reactivated"
}'
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 hoặc REACTIVATE_BANK_ACCOUNT, nếu thiếu bank_account_xid sẽ trả về lỗi 400
  • Diện khôi phục: Purpose REACTIVATE_BANK_ACCOUNT chỉ áp dụng cho tài khoản đang ngừng kích hoạt (bị hủy liên kết kiểu ngừng kích hoạt trước đó); tài khoản không thuộc diện này 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:

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