TVAN

Send e-invoice messages to the TVAN system for processing and forwarding to the tax authority.

API Reference

View TVAN requests, responses and example code

View TVAN 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

Steps to Integrate TVAN

Below are the steps to integrate TVAN into your product.

1. Create a grant /grant/token with scopes set to invoice.

• taxDeclaration (optional): the e-invoice usage registration form details, used to pre-fill the X-Invoice registration form in Cas ID when the user registers. See details

2. Open the Cas Link interface using the grantToken returned in the previous step and select the X-Invoice service. See details

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

4. You can now call the Send Message API.

Registration form details (taxDeclaration)

taxDeclaration is an optional field when creating a grant, applicable to the X-Invoice service. If your system already holds the customer's e-invoice usage registration details, pass them in so that Cas ID can pre-fill the registration form (form 01/ĐKTĐ-HĐĐT), and the user does not have to re-enter them.

Field	Type	Description
email	string	Contact email
registrationType	number	Form type: 1 - New registration, 2 - Change of information
invoiceType	string[]	Invoice form: WITH_TAX_AUTHORITY_CODE - With tax authority code, FROM_POS - Invoice generated from a cash register
invoiceUsageType	string[]	Type of invoice used: VAT - Value-added tax invoice, SALE - Sales invoice

note

For any field you do not pass, Cas ID uses the default value or leaves it blank for the user to fill in.

Call API

Create access grant for TVAN

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": "invoice",
    "language": "vi",
    "redirectUri": "https://your-domain.vn/link",
    "fiServiceId": "6d325840-00d7-11f1-af82-fa163e5398eb",
    "taxDeclaration": {
        "email": "nguyenvana@gmail.com",
        "registrationType": 1,
        "invoiceType": ["WITH_TAX_AUTHORITY_CODE"],
        "invoiceUsageType": ["VAT"]
    }
}'

Javascript (Axios)

 const axios = require('axios');
 const data = JSON.stringify({
   "scopes": "invoice",
   "language": "vi",
   "redirectUri": "https://your-domain.vn/link",
   "fiServiceId": "6d325840-00d7-11f1-af82-fa163e5398eb",
   "taxDeclaration": {
     "email": "nguyenvana@gmail.com",
     "registrationType": 1,
     "invoiceType": ["WITH_TAX_AUTHORITY_CODE"],
     "invoiceUsageType": ["VAT"]
   }
 });

 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 API details, see 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"
  });

  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 API details, see here

API to send e-invoice messages to the TVAN system for processing and forwarding to the tax authority

CURL

  curl --location 'https://sandbox.bankhub.dev/tvan/send' \
  --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>'
  --data-raw '{
    "xmlData": [
      {
        "xml": "<HDon></HDon>"
      }
    ],
    "xmlCount": 1,
    "messageTypeCode": 206
  }'

Javascript (Axios)

  const axios = require('axios');
  let data = JSON.stringify({
    "xmlData": [
      {
        "xml": "<HDon></HDon>"
      }
    ],
    "xmlCount": 1,
    "messageTypeCode": 206
  });

  let config = {
    method: 'post',
    maxBodyLength: Infinity,
    url: 'https://sandbox.bankhub.dev/tvan/send',
    headers: { 
      'Content-Type': 'application/json', 
      'Accept': 'application/json', 
      'x-client-id': '<x-client-id>', 
      'x-secret-key': '<x-client-id>', 
      'Authorization': '<x-client-id>'
    },
    data : data
  };

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

info

For API details, see here