Virtual Account

Personal

Business

Create a Virtual Account

API Reference

View Virtual Account requests, responses and example code

View Virtual Account 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

A Virtual Account is a sub-account directly linked to the customer’s main bank account.
The Virtual Account number is designed and displayed as a string of alphanumeric characters following the VA structure provided by Cas.

Virtual Accounts function as beneficiary account numbers, enabling easier receivables management,
reducing the number of collection accounts needed at banks, and allowing businesses to proactively create and manage Virtual Accounts conveniently for users.

The "Virtual Account for Soundbox" solution is specially designed for Soundbox devices – automated voice alert speakers at stores.
When a transaction is received into a Virtual Account, the system recognizes it and triggers the Soundbox to announce the amount out loud, e.g., “You have received 50,000 VND.”
See product: https://loax.vn

Steps to Integrate Virtual Account

Below are the steps to integrate Virtual Account into your product.

Create a grant /grant/token with scopes set to virtual_account,
virtualAccountNumber configured based on the structure provided by Cas, and fiServiceId being the financial service code registered for this VA.
- virtualAccountNumber: will be configured specifically for each application and corresponding financial service.
- fiServiceId: you can call the API /fi-services to retrieve this information.
- 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 Cas Link interface using the grantToken returned in the previous step. See details
After the user completes authentication, your frontend will receive a publicToken. Use this token to obtain the accessToken for the grant.
After getting the accessToken, call the Get Virtual Account Identity API to verify account details and begin adding it to your system.
If the VA is not valid in your system, call the API /grant/remove to revoke the grant.

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.
Help verify the account: this information is sent along when Cas Link checks the account with the financial service, which surfaces early any case where the account registering the Virtual Account does not match the customer in your system.

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 left blank for the user to fill in.

Call API

Create Grant for Virtual Account

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": "virtual_account",
    "language": "vi",
    "redirectUri": "https://your-domain.vn/link",
    "fiServiceId": "ebf7fe6d-af63-11ee-aa7e-42010a400022",
    "virtualAccountNumber": "V3CASLWXF4RGGY6",
    "user": {
        "companyName": "CONG TY TNHH ABC",
        "companyLegalId": "0312345678",
        "mobileNumber": "0901234567",
        "email": "ketoan@abc.vn"
    }
}'

 const axios = require('axios');
 const data = JSON.stringify({
   "scopes": "virtual_account",
   "language": "vi",
   "redirectUri": "https://your-domain.vn/link",
   "fiServiceId": "ebf7fe6d-af63-11ee-aa7e-42010a400022",
   "virtualAccountNumber": "V3CASLWXF4RGGY6",
   "user": {
     "companyName": "CONG TY TNHH ABC",
     "companyLegalId": "0312345678",
     "mobileNumber": "0901234567",
     "email": "ketoan@abc.vn"
   }
 });

 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

Get accessToken from publicToken

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"
  });

  let 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

Retrieve Identified Account Information

CURL
Javascript (Axios)

  curl --location 'https://sandbox.bankhub.dev/virtual-account/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/virtual-account/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);
  });

info

For detail API, here

Create a Virtual Account​

API Reference

Quickstart

AI Agent

Steps to Integrate Virtual Account​

Customer information (user)​

Call API​

Create Grant for Virtual Account​

Get accessToken from publicToken​

Retrieve Identified Account Information​

Create a Virtual Account

Steps to Integrate Virtual Account

Customer information (`user`)

Call API

Create Grant for Virtual Account

Get accessToken from publicToken

Retrieve Identified Account Information