Notifications and Virtual Accounts

❗️
Attention
Access to this feature is limited to existing Virtual Account users on PayGo and higher tiers who registered before November 24, 2025

Tatum Virtual Accounts (VA), webhook notifications work as subscriptions to the accounts.

When you set up a subscription, the account specified in the id field will be monitored for the blockchain event specified in the type field.

This notification is fired as an HTTP POST request with a JSON body and contains fields like the transaction amount, currency, and account of the incoming transaction. Users should see somewhere in their wallet page that there are pending incoming transactions - their crypto deposits.

To set up webhook notifications for incoming blockchain transactions, use the following v3 REST API endpoint.

Example request:

The result is the ID of the subscription for monitoring, update, or deletion.

curl --request POST \
  --url https://api.tatum.io/v3/subscription \
  --header 'content-type: application/json' \
  --header 'x-api-key: {YOUR_API_KEY}' \
  --data '{
     "type":"ACCOUNT_INCOMING_BLOCKCHAIN_TRANSACTION", // Type of subscription you are creating
     "attr":{
        "id":"5e6be8e9e6aa436299950c41", // The Virtual_Account_ID
        "url":"https://webhook.tatum.io/account" //The URL of the webhook listener you are using
        }
     }'
//Response:
{
    "id": "5fef7ab888eef2e9e4927913" //Subscription_ID
}

🚧
It is strongly encouraged to track and log your "Subscription_ID"

Virtual Accounts Subscription Types:

ACCOUNT_INCOMING_BLOCKCHAIN_TRANSACTION - supported by the rest of the chains.
ACCOUNT_PENDING_BLOCKCHAIN_TRANSACTION - supported only for: BCH, BTC, DOGE, ETH, and LTC accounts.
ACCOUNT_BALANCE_LIMIT - Account balances above a certain limit
TRANSACTION_IN_THE_BLOCK - When outgoing ledger transaction is included in a block
CUSTOMER_TRADE_MATCH - Customer trade matches (in exchanges)
CUSTOMER_PARTIAL_TRADE_MATCH - Customer trade matches (in exchanges)
KMS_COMPLETED_TX
KMS_FAILED_TX