Create Link Token API

API to create a link token for accessing the Bank Hub WebView. The link token allows users to link or unlink bank accounts through the WebView interface.

API Endpoint

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

Request Body

company_xidstringrequired

Company XID - the company performing the link/unlink operation

purposeenumrequired

Purpose of creating link token

completion_redirect_uristring

Redirect URL after completing the flow

is_mobile_appenum

Whether flow is opened from mobile app (1) or web (0)

Default: 0
languageenum

Interface display language

Default: vi
bank_account_xidstring

Bank Account XID. Required when purpose = UNLINK_BANK_ACCOUNT

Headers

company_xidstringrequired

Company XID - the company performing the link/unlink operation

purposeenumrequired

Purpose of creating link token

completion_redirect_uristring

Redirect URL after completing the flow

is_mobile_appenum

Whether flow is opened from mobile app (1) or web (0)

Default: 0
languageenum

Interface display language

Default: vi
bank_account_xidstring

Bank Account XID. Required when purpose = UNLINK_BANK_ACCOUNT

Note
  • This API requires a Bearer Token in the Authorization header
  • Link tokens have a limited validity period (see the expires_at field)
  • Use hosted_link_url to open the WebView for users
  • For purpose UNLINK_BANK_ACCOUNT, bank_account_xid is mandatory
  • For purpose LINK_BANK_ACCOUNT, bank_account_xid is not required
  • bank_account_xid can be obtained from the linked bank account list Bank Account List API

Error Handling

400Validation Error

Invalid input data (company_xid not found, invalid purpose format, missing bank_account_xid when UNLINK)

401Unauthorized

Invalid or expired access token

404Not Found

Company or bank account not found

API Response

Response 201 - Created Successfully
{
  "xid": "string",
  "hosted_link_url": "https://example.com",
  "link_token": "string",
  "expires_at": "string"
}
xidstring

Unique ID of the link token

hosted_link_urlstring

Complete WebView URL to open in iframe or SDK

link_tokenstring

Unique token for authentication

expires_atstring

Expiration time (yyyy-mm-dd HH:mm:ss)

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

Code Examples

1
2
3
4
5
curl --request POST \
  --url https://bankhub-api-sandbox.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"}'

Usage Examples

JSCreate a link token to link a new bank account
1
2
3
4
5
6
7
8
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"
}'
JSCreate a link token to unlink a bank account
1
2
3
4
5
6
7
8
9
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"
}'
Important Notes
  • Expiration: Link tokens have a limited validity period. Check expires_at and create a new token if expired
  • One-time Use: Each link token can be used only once. After completion (success or failure), a new token must be generated
  • Redirect URI: The completion_redirect_uri must be HTTPS in production
  • Validation: For purpose UNLINK_BANK_ACCOUNT, missing bank_account_xid will result in a 400 error
Suggested Flow
  • Backend creates a link token using this API
  • Backend returns hosted_link_url to the frontend
  • Frontend opens the WebView (iframe or SDK) with the URL
  • The user completes the link/unlink process in the WebView
  • After completion, the user is redirected to completion_redirect_uri (if provided)
  • Backend receives webhook notifications with the result

Next Steps

After successfully creating a link token:

  1. JavaScript SDK - Use the SDK to open Hosted Link and manage events
  2. Webhook Events - Receive notifications when linking succeeds
  3. Link Token Info - Check link token status
  4. Bank Account List - View linked bank accounts
Previous page
—
Next page
—