Bank Hub Hosted Link SDK Javascript

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:

<script src='https://bankhub.sepay.vn/assets/sdk/1.0.0/bankhub.min.js'></script>

Khởi tạo Bankhub Instance

const bankhubInstance = new Bankhub({
  mode: 'modal',

  onSuccess: function (result) {
    console.log('Bank linked successfully', result);
    alert('✅ Liên kết ngân hàng thành công!');
    bankhubInstance.destroy();
  },

  onExit: function (result) {
    console.log('User exited Bank Hub', result);
  },

  onOpen: function (data) {
    console.log('Bank Hub opened', data);
  },

  onExpired: function (data) {
    console.log('Token/Session expired', data);
    alert('⚠️ Token hoặc Session đã hết hạn!\nType: ' + data.expired_type);
  }
});

• Dữ liệu trả về cho hàm onSuccess

{
  "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

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

• Dữ liệu trả về cho hàm onOpen

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

• Dữ liệu trả về cho hàm onExpired

{
  "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

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:

function getHostedLinkUrl () {
  const formData = new FormData();
  formData.append('company_xid', 'd3dafd01-e06b-11f0-b29e-52c7e9b4f41b');
  formData.append('workflow', 'LINK_BANK_ACCOUNT');

  fetch('/bankhub/create_link_token', {
    method: 'POST',
    body: formData
  })
  .then(async (response) => {
    if (!response.ok) {
      throw new Error('Network response was not ok');
    }

    const data = await response.json();
    bankhubInstance.initLink(data.data.hosted_link_url);
  });
}

Mở Bank Hub

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

bankhubInstance.open();

Hủy & giải phóng instance

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

bankhubInstance.destroy();