# Bank Hub Hosted Link SDK Javascript

- Anchor: `bankhub-vi-sdk`
- URL: https://developer.sepay.vn/vi/bankhub/sdk.md
- Description: SDK JavaScript giúp tích hợp Hosted Link Bank Hub nhanh chóng, an toàn và chuẩn hóa.

### Giới thiệu

**SDK JavaScript SePay Bank Hub** cho phép bạn tích hợp giao diện **Hosted Link (Bank Hub)** trực tiếp vào website hoặc web app mà không cần tự xây dựng luồng UI ngân hàng phức tạp.

SDK chịu trách nhiệm:
- Mở và hiển thị Bank Hub Hosted Link
- Quản lý vòng đời phiên liên kết ngân hàng
- Lắng nghe sự kiện và callback từ Bank Hub
- Chuẩn hóa trải nghiệm người dùng khi tích hợp

SDK hoạt động **kết hợp với API Link Token** và **không thay thế backend API**.

---

### Khi nào nên sử dụng SDK?



---

### Kiến trúc tích hợp SDK

Luồng tích hợp SDK chuẩn:

- Backend tạo **Link Token** thông qua API
- Backend trả về `hosted_link_url`
- Frontend khởi tạo SDK Bankhub
- SDK mở Hosted Link cho người dùng
- Người dùng hoàn tất liên kết / hủy liên kết
- Backend xác nhận kết quả qua webhook

---

### Cài đặt SDK

Thêm file SDK vào trang HTML:



---

### Khởi tạo Bankhub Instance



- Dữ liệu trả về cho hàm `onSuccess`
**onSuccess**

```json
{
    "event": "FINISHED_BANK_ACCOUNT_LINK | FINISHED_BANK_ACCOUNT_UNLINK",
    "metadata": {
        "account_number": "string",
        "account_type": "individual | enterprise"
    },
    "timestamp": "string"
}
```


- Dữ liệu trả về cho hàm `onExit`
**onExit**

```json
{
    "event": "BANKHUB_CLOSE_LINK",
    "metadata": {
        "account_number": "string",
        "account_type": "individual | enterprise"
    },
    "timestamp": "string"
}
```


- Dữ liệu trả về cho hàm `onOpen`
**onOpen**

```json
{
    "event": "BANKHUB_OPEN",
    "metadata": {
        "account_number": "string",
        "account_type": "individual | enterprise"
    },
    "timestamp": "string"
}
```


- Dữ liệu trả về cho hàm `onExpired`
**onExpired**

```json
{
    "event": "BANKHUB_TOKEN_EXPIRED | BANKHUB_SESSION_EXPIRED",
    "metadata": {
        "account_number": "string",
        "account_type": "individual | enterprise"
    },
    "timestamp": "string"
}
```


---

### Các option cấu hình SDK

| Option      | Kiểu dữ liệu | Mô tả                                 |
| ----------- | ------------ | ------------------------------------- |
| `mode`      | `string`     | Chế độ hiển thị. Hiện hỗ trợ: `modal`, `newTab`, `newWindow`, `redirect` |
| `onSuccess` | `function`   | Gọi khi liên kết hoặc huỷ liên kết ngân hàng thành công |
| `onExit`    | `function`   | Gọi khi người dùng thoát Bank Hub     |
| `onOpen`    | `function`   | Gọi khi Bank Hub được mở              |
| `onExpired` | `function`   | Gọi khi token hoặc session hết hạn    |

---

### Tạo Link Token (Backend)

SDK **không tự tạo link token**.
- Link token **bắt buộc phải được tạo từ backend**.

- Ví dụ frontend gọi backend để lấy Hosted Link URL:



---

### Mở Bank Hub

- Sau khi đã khởi tạo link bạn có thể mở Bankhub ngay:



---

### Hủy & giải phóng instance

- Sau khi hoàn tất, nên destroy instance:



---

{% callout title="Lưu ý quan trọng" type="warning" %}
* **Không tạo link token ở frontend**
* Không expose Bearer Token hoặc client secret
* Luôn xử lý trường hợp token/session hết hạn


---