SePay Bank Hub JavaScript SDK

Introduction

The SePay Bank Hub JavaScript SDK allows you to integrate the Hosted Link (Bank Hub) interface directly into your website or web app without building complex banking UI flows yourself.

The SDK is responsible for:

• Opening and displaying Bank Hub Hosted Link
• Managing the bank linking session lifecycle
• Listening to events and callbacks from Bank Hub
• Standardizing the user experience during integration

The SDK works in conjunction with the Link Token API and does not replace backend APIs.

When Should You Use the SDK?

SDK Integration Architecture

Standard SDK integration flow:

• Backend creates Link Token via API
• Backend returns hosted_link_url
• Frontend initializes SDK Bankhub
• SDK opens Hosted Link for user
• User completes linking / unlinking
• Backend confirms results via webhook

Installing the SDK

Add the SDK file to your HTML page:

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

Initialize Bankhub Instance

const bankhubInstance = new Bankhub({
mode: 'modal',
 
onSuccess: function (result) {
  console.log('Bank linked successfully', result);
  alert('✅ Bank linked successfully!');
  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 or Session expired!\nType: ' + data.expired_type);
}
});

• Data returned to onSuccess function

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

• Data returned to onExit function

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

• Data returned to onOpen function

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

• Data returned to onExpired function

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

SDK Configuration Options

Create Link Token (Backend)

The SDK does not create link tokens automatically.

• Link tokens must be created from the backend.

• Example frontend calling backend to get 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);
});
}

Open Bank Hub

• After initializing the link, you can open Bankhub immediately:

bankhubInstance.open();

Destroy & Release Instance

• After completion, you should destroy the instance:

bankhubInstance.destroy();