# SDK JavaScript SePay Bank Hub

- Anchor: `bankhub-en-sdk`
- URL: https://developer.sepay.vn/en/bankhub/sdk.md
- Description: JavaScript SDK for quick, secure, and standardized integration with Bank Hub Hosted Link.

### 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ị 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
{
    "type": "bankhub_success",
    "action": "success",
    "workflow": "UNLINK_BANK_ACCOUNT | LINK_BANK_ACCOUNT",
    "data": {
        "bank_code": "string",
        "bank_name": "string",
        "account_number": "string",
        "account_type": "individual | enterprise",
        "account_label": "Cá nhân | Doanh nghiệp",
        "link_token_xid": "string",
        "timestamp": "string"
    }
}
```


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

```json
{
    "type": "bankhub_close",
    "action": "opener",
    "timestamp": "string"
}
```


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

```json
{
    "type": "bankhub_open",
    "hosted_link_url": "string",
    "mode": "modal"
}
```


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

```json
{
    "type": "bankhub_expired",
    "action": "expired",
    "data": {
        "expired_type": "session",
        "session_expired": true,
        "error_view": "error_token_expire | error_session_expire",
        "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 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


---