Quick Start

This guide shows you how to integrate Bank Hub into your app in a few simple steps – from creating tokens and linking them to embedding webview iframes and receiving balance change notifications.

Obtain an access_token from the /v1/token API
Use the access_token to create a link token
Embed the hosted_link_url into an iframe on your website

Before You Start

Make sure you have:

client_id and client_secret provided by SePay
company_xid (UUID of the company created in the Bank Hub system) – Create Company API
A backend server to call APIs (do not call APIs from the client-side for security reasons)

Step 1: Get Access Token

First, you need to obtain an access_token to authenticate subsequent API calls.
This API uses Basic Authentication with client_id and client_secret.

Security

DO NOT call this API from the client-side (browser or mobile app).
This API requires client_secret, which must be strictly protected on the server.
Only call this API from your backend server.

API Endpoint

POST

https://bankhub-api-sandbox.sepay.vn/v1/token

Authorization: Basic {base64(client_id:client_secret)}
Content-Type: application/json

Code examples

php

Response

RESPONSE 201 - Success

{
  "code": 201,
  "access_token": "36483db493b10304eb3abc143b3593fa1473eb9b",
  "ttl": 60000
}

Token Storage

Store the access_token in cache (Redis, Memcached) or session
The token has a limited lifetime (ttl), so implement automatic refresh logic
When receiving a 401 Unauthorized error, automatically request a new token

Step 2: Create Link Token

After obtaining the access_token, use it to create a link token. The link token provides a hosted_link_url, which will be embedded into an iframe.

API Endpoint

POST

[https://bankhub-api-sandbox.sepay.vn/v1/link-token/create](https://bankhub-api-sandbox.sepay.vn/v1/link-token/create)

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Code examples

php

Note

The code examples above demonstrate creating a link token for the bank account linking flow. If you need to create an unlink flow, set purpose to UNLINK_BANK_ACCOUNT and provide bank_account_xid.

Response

RESPONSE 201 - Created

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

Full details of the link token API: Create Link Token API

Step 3: Embed Iframe into Website

After receiving the hosted_link_url from Step 2, you can embed it into your website using an iframe.

Information

If you provided completion_redirect_uri when creating the link token, users will be redirected to that URL after completion.

PostMessage Events

The iframe sends events via window.postMessage in the following format:

event format

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

Event types:

FINISHED_BANK_ACCOUNT_LINK

The bank account has been successfully linked. Metadata contains account information.

FINISHED_BANK_ACCOUNT_UNLINK

The bank account has been successfully unlinked.

BANKHUB_CLOSE_LINK

The user closes or cancels the linking flow.

BANKHUB_TOKEN_EXPIRED

The link token has expired and a new token must be created.

BANKHUB_SESSION_EXPIRED

The session has expired and must be re-initialized.

Configure Balance Change Notifications (IPN)

➤ You can view the details here