SupportStatusDashboard

Adding FIAT Currencies

How to create Virtual Accounts with FIAT Currencies

Suggest Edits

Virtual Accounts (VA) can support FIAT currencies in the VA ledger.

FIAT currencies are registered as Virtual Currencies (VC). After you create a VC, you can create a VA with said currency and issue transactions across accounts within the VA ledger.

Steps

Step_1: Create a Virtual Currency on a Virtual Account based on FIAT

Example request:

  • The response included a Virtual Account of the given VC.
  • The initial supply of the VC is already credited to the account.
curl --location --request POST 'https://api.tatum.io/v3/ledger/virtualCurrency' \
--header 'x-api-key:{YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "VC_USD",
    "supply": "100000",
    "basePair": "USD"
}'
//Response:
{
    "balance": {
        "accountBalance": "100000",
        "availableBalance": "100000"
    },
    "active": true,
    "frozen": false,
    "currency": "VC_USD",
    "accountingCurrency": "EUR",
    "id": "5fbe46739045a09adbc3f590" //This is the first "Virtual_Account_Id" within your ledger using VC_USD
}

import {Currency, Fiat, createVirtualCurrency } from '@tatumio/tatum';
/**
 * Create new virtual currency with given supply stored in account.
 * This will create Tatum internal virtual currency.
 * @param data - body of request - https://apidoc.tatum.io/tag/Virtual-Currency/#operation/createCurrency
 * @returns virtual currency detail
 */
const body = {
  name: "VC_USD",
  supply: "100000",
  basePair: USD
  }
const vc = createVirtualCurrency (body);

Step_2: Increasing the supply of a VC within an Account

When you want to increase the supply of a VC, you have to mint new units. Minted units are credited to the specific virtual account, and the operation is visible as a new virtual account transaction for that account.

Example request:

  • The response includes a reference to the Virtual Account transaction.
curl --location --request PUT 'https://api.tatum.io/v3/ledger/virtualCurrency/mint' \
--header 'x-api-key: {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "accountId": "5fbe46739045a09adbc3f590",
    "amount": "100"
}'
//Response:
{
    "reference": "c7b8ca84-bab3-42d0-9115-90fad09e5f57"
}

import { mintVirtualCurrency } from '@tatumio/tatum';
/**
 * Create new supply of virtual currency linked on the given accountId.
 * @param data - body of request - https://apidoc.tatum.io/tag/Virtual-Currency/#operation/mintCurrency
 * @returns transaction internal reference
 */
const body = {
  accountId: "5fbe46739045a09adbc3f590",
  amount: "100",
  }
const mint = mintVirtualCurrency (body);

Step_3: Destroying the supply of a VC within an Account

When you want to destroy the supply of a VC, you have to revoke some units. Destroyed units are debited from the specific virtual account, and the operation is visible as a new virtual account transaction for the account.

Request example:

  • The response includes a reference ID for the virtual account transaction.
curl --location --request PUT 'https://api.tatum.io/v3/ledger/virtualCurrency/revoke' \
--header 'x-api-key: {YOUR_API_KE}Y' \
--header 'Content-Type: application/json' \
--data-raw '{
    "accountId": "5fbe46739045a09adbc3f590",
    "amount": "100"
}'
//Response:
{
    "reference": "e9574b40-4b25-4f03-be76-27cec5e564fc"
}

import { revokeVirtualCurrency } from '@tatumio/tatum';
/**
 * Destroy supply of virtual currency linked on the given accountId.
 * @param data - body of request - https://apidoc.tatum.io/tag/Virtual-Currency/#operation/revokeCurrency
 * @returns transaction internal reference
 */
const body = {
  accountId: "5fbe46739045a09adbc3f590",
  amount: "100",
  }
const burn = revokeVirtualCurrency (body);

Step_4: Listing VA transactions

Using the VA account_ID, we can now get the list of transactions from said account.

Request example:

  • In the response, we can see the two transactions we have just performed - mint and revoke.
curl --location --request POST 'https://api.tatum.io/v3/ledger/transaction/account?pageSize=50' \
--header 'x-api-key: {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": "5fbe46739045a09adbc3f590"
}'
//Response:
[
    {
        "amount": "-100",
        "operationType": "REVOKE",
        "currency": "VC_USD",
        "transactionType": "DEBIT_OUTGOING_PAYMENT",
        "accountId": "5fbe46739045a09adbc3f590",
        "anonymous": false,
        "reference": "e9574b40-4b25-4f03-be76-27cec5e564fc",
        "senderNote": null,
        "recipientNote": null,
        "paymentId": null,
        "transactionCode": null,
        "marketValue": {
            "currency": "EUR",
            "source": "Fixer.io",
            "sourceDate": 1606302850000,
            "amount": "-84.13613226199991586387"
        },
        "created": 1606305988347
    },
    {
        "amount": "100",
        "operationType": "MINT",
        "currency": "VC_USD",
        "transactionType": "CREDIT_INCOMING_PAYMENT",
        "accountId": "5fbe46739045a09adbc3f590",
        "anonymous": false,
        "reference": "c7b8ca84-bab3-42d0-9115-90fad09e5f57",
        "recipientNote": null,
        "paymentId": null,
        "transactionCode": null,
        "marketValue": {
            "currency": "EUR",
            "source": "Fixer.io",
            "sourceDate": 1606302850000,
            "amount": "84.13613226199991586387"
        },
        "created": 1606305827044
    }
]

import {getTransactionsByAccount} from '@tatumio/tatum';
/**
 * Finds transactions for the account identified by the given account ID.
 * @param filter - request body with data filter - https://apidoc.tatum.io/tag/Transaction/#operation/getTransactionsByAccountId
 * @param pageSize - max number of items per page is 50.
 * @param offset - optional Offset to obtain next page of the data.
 */
const filter = {
  id: "5fbe46739045a09adbc3f590",
  }
const tx = getTransactionsByAccount(filter,50,0);

General Integration Steps

  • When you receive a payment into your bank account or via a card transaction, you can mint a new supply on the connected user account.
  • When you send a payment from your bank account, you can revoke the supply from the connected user account.
  • You will then perform all internal transactions within the Tatum virtual accounts and your application ecosystem.

🚧

It is not possible to integrate the Tatum VA ledger directly into a specific bank or card processor to read and perform bank transactions. This is due to legislative restrictions. Bank integration must be done in your application and reflect your bank operations into Tatum.

Good to Know

  • A FIAT currency is a government-issued currency that isn't backed by a commodity such as gold.
  • A Virtual Currency is an entity in the virtual account distributed database. It is created with an initial supply of coins. This supply can be extended or reduced at any time.
  • Virtual Accounts should be assigned to "customers" at creation. The "customer" inside the VA ledger is an entity containing information about your application's user, such as the customer's country of residence, accounting currency, and other. The parameter "externalId" is the identifier of your users in your database.
  • Every virtual Currency (VC) inside the Virtual Account ledger is pegged to a currency from the outside world. It can be a blockchain asset or FIAT currency. This means that one unit of the virtual currency is equal to one unit of the pegged currency.
  • When you create a Virtual Currency VC_USD with the base pair USD, 1 VC_USD = 1 USD, you can set your custom base rate, e.g., 1 VC_USD = 2 USD with the base rate 2.

Updated about 1 month ago