Balance Hook

Personal

Business

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

AI Agent

Install skills so your AI coding agent integrates Cas correctly for your codebase

Build with AI Agent

How It Works

You configure a webhook_url in the Cas system – this is the URL where Cas will send notifications of balance changes.
When a balance change event occurs, Cas will send an HTTP POST request to that URL.
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.

Create a permission /grant/token with the scopes value set to qrpay or virtual_account.
- user (optional): the customer information already stored in your system, used to prefill the linking form on Cas Link and to help verify the account information. See details
Open the Cas Link interface using the returned grantToken to let users link their bank accounts. See details
Receive the publicToken once the user completes the linking process, and use it to obtain an accessToken.
Configure the webhook endpoint to receive notifications — CAS.SO will send balance change data whenever a new transaction occurs.

Customer information (`user`)

user is an optional field when creating a grant. If your system already stores the customer's information, send it so that Cas Link can:

Prefill the linking form: Cas Link fills in the account holder name, identification number, phone number and email, so the user does not have to re-enter what you already have.
Validate the bank account: with scopes set to qrpay, Cas Link compares the information you send with the account information returned by the bank; if the account holder name or the identification number does not match, the linking flow is stopped and an error is shown to the user.

Field	Type	Description
`legalName`	string	Account holder name (individual)
`idNumber`	string	Personal identification number (ID card) of the account holder
`companyName`	string	Company name
`companyLegalId`	string	Tax code / business registration number
`mobileNumber`	string	Phone number registered with the bank
`email`	string	Customer email

note

Depending on whether the financial service is of type personal or enterprise, send either legalName/idNumber or companyName/companyLegalId. Any field you omit is skipped during the comparison.

Call API

Create permission for Balance Hook

CURL
Javascript (Axios)

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",
    "user": {
        "legalName": "NGUYEN VAN A",
        "idNumber": "079201000123",
        "mobileNumber": "0901234567",
        "email": "nguyenvana@gmail.com"
    }
}'

 const axios = require('axios');
 const data = JSON.stringify({
   "scopes": "qrpay", // or virtual_account
   "language": "vi",
   "redirectUri": "https://your-domain.vn/link",
   "user": {
     "legalName": "NGUYEN VAN A",
     "idNumber": "079201000123",
     "mobileNumber": "0901234567",
     "email": "nguyenvana@gmail.com"
   }
 });

 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
Javascript (Axios)

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

  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
Javascript (Axios)

  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>'

  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.

API Reference

Quickstart

AI Agent

How It Works​

Integration Steps​

Customer information (user)​

Call API​

Create permission for Balance Hook​

Exchange publicToken for accessToken​

Fetch identity and account information for the granted account​

Receive balance change notifications​