# Create Link Token API

- Anchor: `bankhub-en-api-link-token-tao-link-token`
- URL: https://developer.sepay.vn/en/bankhub/api/link-token/tao-link-token.md
- Description: 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.

**POST** `https://bankhub-api-sandbox.sepay.vn/v1/link-token/create`
```http
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
```



**Request Body**

<!-- Params table -->

**Headers**

<!-- Params table -->

> **Note** (info)
>
>
> * 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
>

| Code | Name | Description |
|------|------|-------------|
| 400 | Validation Error | Invalid input data (company_xid not found, invalid purpose format, missing bank_account_xid when UNLINK) |
| 401 | Unauthorized | Invalid or expired access token |
| 404 | Not Found | Company or bank account not found |







**RESPONSE 201 - Created Successfully**


```json
{
  "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"
}
```





**RESPONSE 400 - Validation Error**


```json
{
  "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"]
  }
}
```








---

### Usage Examples

{% node
title="Create a link token to link a new bank account"
code="curl --location '[https://bankhub-api-sandbox.sepay.vn/v1/link-token/create](https://bankhub-api-sandbox.sepay.vn/v1/link-token/create)' \\n  --header 'Content-Type: application/json' \\n  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \\n  --data '{\n    "company_xid": "d3dafd01-e06b-11f0-b29e-52c7e9b4f41b",\n    "purpose": "LINK_BANK_ACCOUNT",\n    "completion_redirect_uri": "[https://yourapp.com/success\"\n](https://yourapp.com/success\%22\n)  }'"
/%}

{% node
title="Create a link token to unlink a bank account"
code="curl --location '[https://bankhub-api-sandbox.sepay.vn/v1/link-token/create](https://bankhub-api-sandbox.sepay.vn/v1/link-token/create)' \\n  --header 'Content-Type: application/json' \\n  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \\n  --data '{\n    "company_xid": "d3dafd01-e06b-11f0-b29e-52c7e9b4f41b",\n    "purpose": "UNLINK_BANK_ACCOUNT",\n    "bank_account_xid": "f414b73c-eebe-11f0-b16e-52c7e9b4f41b",\n    "completion_redirect_uri": "[https://yourapp.com/unlinked\"\n](https://yourapp.com/unlinked\%22\n)  }'"
/%}

---

> **Important Notes** (warn)
>
>
> * **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** (info)
>
>
> * 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
>

---