API Tạo Link Token

API tạo link token để truy cập WebView Bank Hub. Link token cho phép người dùng liên kết hoặc hủy liên kết tài khoản ngân hàng thông qua giao diện WebView.

POST

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

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Request Body

Tên	Loại	Bắt buộc	Mô tả
`company_xid`	string	Bắt buộc	Company XID (UUID) – công ty thực hiện liên kết/hủy liên kết tài khoản ngân hàng.
`purpose`	string	Bắt buộc	Mục đích tạo link token. Giá trị: `LINK_BANK_ACCOUNT` (liên kết tài khoản ngân hàng mới) hoặc `UNLINK_BANK_ACCOUNT` (hủy liên kết tài khoản ngân hàng).
`completion_redirect_uri`	string	Không bắt buộc	URL chuyển hướng sau khi hoàn thành flow. Người dùng sẽ được redirect về URL này sau khi kết thúc phiên link.
`is_mobile_app`	integer	Không bắt buộc	Xác định flow được mở từ mobile app hay web. Giá trị: `0` = Web (mặc định), `1` = Mobile App.
`language`	string	Không bắt buộc	Ngôn ngữ hiển thị giao diện hosted link. Giá trị: `vi`, `en`. Mặc định: `vi`.
`bank_account_xid`	string	Không bắt buộc	Bank Account XID (UUID). Bắt buộc khi `purpose = UNLINK_BANK_ACCOUNT`.

Headers

Tên	Loại	Bắt buộc	Mô tả
`Authorization`	Bearer Token	Bắt buộc	Access token lấy từ API /v1/token
`Content-Type`	string	Bắt buộc	application/json

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

400	Validation 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)	—
401	Unauthorized Access token không hợp lệ hoặc đã hết hạn	—
404	Not Found Công ty hoặc tài khoản ngân hàng không tồn tại	—

bash

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"
}

xidstring

ID duy nhất của link token (UUID format).

hosted_link_urlstring

URL WebView hoàn chỉnh để mở trong iframe hoặc SDK. Người dùng truy cập URL này để liên kết/hủy liên kết tài khoản.

link_tokenstring

Token duy nhất để xác thực. Có thể dùng thay thế hosted_link_url.

expires_atdatetime

Thời điểm hết hạn của link token (yyyy-mm-dd HH:mm:ss).

RESPONSE 400 - Lỗi validation

{
  "code": 400,
  "message": "Validation error",
  "errors": {
    "company_xid": [
      "Company not found"
    ],
    "purpose": [
      "Purpose must be LINK_BANK_ACCOUNT or UNLINK_BANK_ACCOUNT"
    ],
    "bank_account_xid": [
      "Bank account XID is required when purpose is UNLINK_BANK_ACCOUNT"
    ]
  }
}

codeinteger

Mã lỗi HTTP.

messagestring

Thông báo lỗi tổng quát.

errorsobject

Chi tiết lỗi validation cho từng trường.

Ví dụ sử dụng

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

curl --location 'https://bankhub-api-sandbox.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"
  }'

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

curl --location 'https://bankhub-api-sandbox.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ả