# API Tạo Link Token

- Anchor: `bankhub-vi-api-link-token-tao-link-token`
- URL: https://developer.sepay.vn/vi/bankhub/api/link-token/tao-link-token.md
- Description: 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`
```http
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
```


**Request Body**

<!-- Params table -->

**Headers**

<!-- Params table -->

> **Lưu ý** (info)
>
> - 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](vi/bankhub/api/tai-khoan-ngan-hang/danh-sach-tai-khoan)**
>

| Code | Name | Description |
|------|------|-------------|
| 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 |







**RESPONSE 201 - Tạo thành công**


```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 - Lỗi validation**


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








---

### Ví dụ sử dụng





---

> **Lưu ý quan trọng** (warn)
>
> - **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** (info)
>
> - 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ả
>

---