Balance Hook

Balance Hook is an event webhook provided by Cas to instantly notify you of any balance changes on a linked bank account or virtual account (VA).

Whenever a user deposits, withdraws, or triggers a transaction that alters the account balance, your system will receive a POST call from Cas. This allows you to process transactions quickly and automatically without the need for constant polling.

API Reference

View Balance Hook requests, responses and example code

View Balance Hook API

Quickstart

Learn about the information to deploy and how it works.

Get started

How It Works

1. You configure a webhook_url in the bankHub system – this is the URL where bankHub will send notifications of balance changes.
2. When a balance change event occurs, bankHub will send an HTTP POST request to that URL.
3. Your system processes the received payload to perform actions such as: recording the transaction, sending notifications, etc.

Integration Steps

Below are the steps to integrate the Balance Hook into your product.

1. Create a permission /grant/token with the scopes value set to transactions.

2. Open the Cas Link interface using the returned grantToken to let users link their bank accounts. See details

3. Receive the publicToken once the user completes the linking process, and use it to obtain an accessToken.

4. Configure the webhook endpoint to receive notifications — CAS.SO will send balance change data whenever a new transaction occurs.

Call API

Create permission for Balance Hook

CURL

curl --location 'https://sandbox.bankhub.dev/grant/token' \
--header 'X-BankHub-Api-Version: 2023-01-01' \
--header 'x-client-id: <CLIENT_ID_HERE>' \
--header 'x-secret-key: <SECRET_KEY_HERE>' \
--header 'Content-Type: application/json' \
--data '{
    "scopes": "qrpay",
    "language": "vi",
    "redirectUri": "https://your-domain.vn/link",
}'

Javascript (Axios)

 const axios = require('axios');
 const data = JSON.stringify({
   "scopes": "qrpay", // or virtual_account
   "language": "vi",
   "redirectUri": "https://your-domain.vn/link",
 });

 const config = {
   method: 'post',
   maxBodyLength: Infinity,
   url: 'https://sandbox.bankhub.dev/grant/token',
   headers: { 
     'X-BankHub-Api-Version': '2023-01-01', 
     'x-client-id': '<CLIENT_ID_HERE>', 
     'x-secret-key': '<SECRET_KEY_HERE>', 
     'Content-Type': 'application/json',
   },
   data: data
 };

 axios.request(config)
 .then((response) => {
   console.log(JSON.stringify(response.data));
 })
 .catch((error) => {
   console.log(error);
 });

info

For detail API, here

Exchange publicToken for accessToken

CURL

  curl --location 'https://sandbox.bankhub.dev/grant/exchange' \
  --header 'X-BankHub-Api-Version: 2023-01-01' \
  --header 'x-client-id: <CLIENT_ID_HERE>' \
  --header 'x-secret-key: <SECRET_KEY_HERE>' \
  --header 'Content-Type: application/json' \
  --data '{
      "publicToken": "bdbde2bad-7685-4f95-987c-71309a4a3"
  }'

Javascript (Axios)

  const axios = require('axios');
  const data = JSON.stringify({
    "publicToken": "bdbde2bad-7685-4f95-987c-71309a4a3"
  });

  const config = {
    method: 'post',
    maxBodyLength: Infinity,
    url: 'https://sandbox.bankhub.dev/grant/exchange',
    headers: { 
      'X-BankHub-Api-Version': '2023-01-01', 
      'x-client-id': '<CLIENT_ID_HERE>', 
      'x-secret-key': '<SECRET_KEY_HERE>', 
      'Content-Type': 'application/json'
    },
    data: data
  };

  axios.request(config)
    .then((response) => {
      console.log(JSON.stringify(response.data));
    })
    .catch((error) => {
      console.log(error);
    });

info

For detail API, here

Fetch identity and account information for the granted account

CURL

  curl --location 'https://sandbox.bankhub.dev/identity' \
  --header 'X-BankHub-Api-Version: 2023-01-01' \
  --header 'Authorization: <ACCESS_TOKEN_HERE>' \
  --header 'x-client-id: <CLIENT_ID_HERE>' \
  --header 'x-secret-key: <SECRET_KEY_HERE>'

Javascript (Axios)

  const axios = require('axios');

  let config = {
    method: 'get',
    maxBodyLength: Infinity,
    url: 'https://sandbox.bankhub.dev/identity',
    headers: { 
      'X-BankHub-Api-Version': '2023-01-01', 
      'Authorization': '<ACCESS_TOKEN_HERE>', 
      'x-client-id': '<CLIENT_ID_HERE>', 
      'x-secret-key': '<SECRET_KEY_HERE>'
    }
  };

  axios.request(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });

Receive balance change notifications

• You need to configure a TRANSACTIONS-type Webhook in the Developer Console — this is the URL where Cas will send notifications when balance changes occur.
• When a balance change event is triggered, Cas will send an HTTP POST request to that URL.
• our system will process the received payload to handle business logic such as recording transactions, sending alerts, etc.

Sample webhook data

{
  "environment": "dev",
  "webhookType": "TRANSACTIONS",
  "webhookCode": "DEFAULT_UPDATE",
  "error": null,
  "grantId": "4c657924-13f3-11ee-a4bb-42010a40001b",
  "transaction": {
    "id": "3cacecf6935011ee952542010a400022",
    "transactionCode": "993UNdEHhIgfy3I",
    "reference": null,
    "transactionDate": "2023-12-05",
    "transactionDateTime": "2023-12-05T16:25:00+07:00",
    "bookingDate": "2023-12-05",
    "amount": 10000,
    "description": "test",
    "runningBalance": 3330000,
    "accountNumber": 867623232,
    "virtualAccountNumber": null,
    "virtualAccountName": null,
    "paymentChannel": null,
    "counterAccountNumber": null,
    "counterAccountName": null,
    "counterAccountBankId": null,
    "counterAccountBankName": null,
    "paymentMeta": null,
    "fiId": "3c26a8ed-efb5-11ed-8620-0ae7e48c82d8",
    "fiName": "VietinBank",
    "fiServiceId": "433f71c4-efb5-11ed-8620-0ae7e48c82d8",
    "fiServiceName": "VietinBank iPay - Official API",
    "currency": "VND"
  }
}

INFORMATION

For detail API, here.