Virtual Account

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

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.

1. 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.

2. Open Cas Link interface using the grantToken returned in the previous step. See details

3. After the user completes authentication, your frontend will receive a publicToken. Use this token to obtain the accessToken for the grant.

4. After getting the accessToken, call the Get Virtual Account Identity API to verify account details and begin adding it to your system.

5. If the VA is not valid in your system, call the API /grant/remove to revoke the grant.

Call API

Create Grant for Virtual Account

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": "virtual_account",
    "language": "vi",
    "redirectUri": "https://your-domain.vn/link",
    "fiServiceId": "ebf7fe6d-af63-11ee-aa7e-42010a400022",
    "virtualAccountNumber": "V3CASLWXF4RGGY6"
}'

Javascript (Axios)

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

 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

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

  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

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

Javascript (Axios)

  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