Headless Deposit Tracking Session

Overview

Headless Deposit Tracking allows merchants to track user deposits without a checkout page.

With this approach, merchants can fully manage the user experience on their own UI while still benefiting from the platform’s blockchain address management and deposit detection capabilities.

The main goal of headless deposit tracking is simple:

Enable deposit detection and tracking without requiring the user to open or interact with a hosted checkout page.

---

How the Service Works

When the session-headless endpoint is called, the service performs two core operations in sequence:

1. Session Creation Decision (Automatic & Conditional)

The system first determines whether a standard deposit-tracking session should be created for the given customer and the user.

• If the user already has a recently created session (within the last 1 hour), no new session is created.

• If no valid session exists, the system automatically starts a normal deposit-tracking session in the background.

This process is fully automatic and asynchronous. Merchants do not need to manage or track session creation manually.

2. Returning User Blockchain Addresses

After the session decision is made, the service immediately returns the user’s blockchain deposit addresses.

The system:

• Reads the list of enabled checkout currencies for the merchant.

• Fetches the user’s currently assigned blockchain addresses.

• Maps addresses per blockchain network.

Design note:

All ETH-based networks (ETH and ERC20 tokens) use the same ETH address by design.

Asynchronous Address Initialization & Address States

Blockchain address creation and activation are asynchronous processes.

For this reason, each returned address includes a state indicating its readiness.

Each address contains:

• chain: Blockchain network (e.g. BTC, ETH, USDT_TRON)

• userAddressState:

  • Ready → Address is available and can be shown to the user.

  • Empty → Address is not yet created or activated.

• blockchainAddress: The deposit address or "-" if not yet available.

• destinationTag (optional): Returned only for networks that require it (e.g. XRP).

Merchants are expected to retry the endpoint until all required addresses reach the Ready state.

Here is a sample result after creating a headless session.

{
    userAddresses: [
      {
        chain: 'BTC',
        userAddressState: 'Ready',
        blockchainAddress: 'bc1qvhaxu6jpxzrflh2grukhtsl9trq6w6ddnd3kwz',
      },
      {
        chain: 'DOGE',
        userAddressState: 'Ready',
        blockchainAddress: 'DCnLffp4GJX7k4LHkRPKuWa4aHXyCDm9nU',
      },
      {
        chain: 'ETH',
        userAddressState: 'Empty',
        blockchainAddress: '-',
      },
      {
        chain: 'LTC',
        userAddressState: 'Empty',
        blockchainAddress: '-',
      },
      {
        chain: 'TRON',
        userAddressState: 'Empty',
        blockchainAddress: '-',
      },
      {
        chain: 'USDC_ERC20',
        userAddressState: 'Empty',
        blockchainAddress: '-',
      },
      {
        chain: 'USDT_ERC20',
        userAddressState: 'Empty',
        blockchainAddress: '-',
      },
      {
        chain: 'USDT_TRON',
        userAddressState: 'Empty',
        blockchainAddress: '-',
      },
      {
        chain: 'XRP',
        userAddressState: 'Empty',
        blockchainAddress: '-',
      },
    ],
  }

Recommended Step-by-Step Flow

This section describes the recommended integration flow for Headless Deposit Tracking.

Following this sequence ensures that blockchain addresses are prepared as early as possible and deposit detection works reliably.

1

Create a Normal Deposit Tracking Session

This step can be triggered as soon as the user logs in to the merchant’s system. Please see Deposit Tracking Session

Before using headless deposit tracking, it is strongly recommended to create a standard deposit-tracking session for the user.

Why is this step important?

• Blockchain address creation and activation are asynchronous.

• Creating a normal session in advance allows the system to:

  • Generate user blockchain addresses early.

  • Activate internal tracking and monitoring processes.

• This significantly increases the chance that addresses will already be in the Ready state when the headless session is requested.

2

Create a Headless Deposit Tracking Session

Once the system has had time to prepare user addresses, the merchant should call the Headless Session endpoint.

In this step:

• The system checks whether a valid session already exists.

• If necessary, a normal session is automatically triggered in the background.

• The user’s blockchain addresses are returned immediately with their current states.

Each returned address includes:

• Blockchain network (chain)

• Address readiness state (Ready or Empty)

• Blockchain address

• Optional destination tag (for supported networks)

Expected behavior

• Some addresses may still be returned as Empty.

• The client should retry or poll until all required addresses become Ready.

3

Implement Client-Side Refresh / Retry Until Addresses Are Ready

Because blockchain address creation and activation are asynchronous, the first headless session response may include addresses with the state Empty.

In this step, the client should implement a simple refresh strategy:

Recommended behavior

• If any required address is returned as Empty, the client should:

  • Display a “preparing addresses” message in the UI, and

  • Add a retry button to refresh the request and update the user interface.

A Sample Code For Creating A Headless Deposit Tracking Session

Below, you can find an example of how to create a headless deposit tracking session using TypeScript code.

import {createHmac} from 'crypto';

const hmacSecretKey = 'YOUR HMAC SECRET Key';
const xApiKey = 'YOUR API KEY'

const payloadPgHeadless = {
    userId: 'YOUR_UNIQUE_USER_ID',
};

const body = JSON.stringify(payloadPgHeadless);
const xPayloadHash = createHmac('sha512', hmacSecretKey).update(body)
                .digest('base64');

try {
    const sessionCreationResult = await axios.post(
        'https://api-prod.alfa-instap-cpt.uk/pgpub/session-headless', body,
        {
            timeout: 6000,
            headers: {
                "content-type": "application/json",
                "x-api-key": xApiKey,
                "x-payload-hash": xPayloadHash,
            }
        }
    );
    console.log(sessionCreationResult.data);
} catch (error) {
    console.log(error);
    throw new Error('Session creation failed');
}

POST https://api-prod.alfa-instap-cpt.uk/pgpub/session-headless

Headers

Name		Value
content-type*	string	application/json
x-api-key*	string	Replace your API key
x-payload-hash*	string	Replace your calculated HMAC hash. See API Security.

Body

Name	Type	Description
userId*	string	STRING [Min 1,Max 4000] Characters The userId field is your user's unique Id. The system uses this parameter to track deposit events, and it distinguishes deposit sessions using this parameter. userId parameter must be unique within the customer's infrastructure.

Response

200

{
  userAddresses: [
    {
      chain: 'BTC',
      userAddressState: 'Ready',
      blockchainAddress: 'bc1qvhaxu6jpxzrflh2grukhtsl9trq6w6ddnd3kwz'
    },
    {
      chain: 'DOGE',
      userAddressState: 'Ready',
      blockchainAddress: 'DCnLffp4GJX7k4LHkRPKuWa4aHXyCDm9nU'
    },
    {
      chain: 'ETH',
      userAddressState: 'Ready',
      blockchainAddress: '0xea99ec58006c78fcb01625d2a5466016afd98ac4'
    },
    {
      chain: 'LTC',
      userAddressState: 'Ready',
      blockchainAddress: 'LUuks5yjRmE72nPUPG98kGKF7ey6MLxVYs'
    },
    {
      chain: 'TRON',
      userAddressState: 'Ready',
      blockchainAddress: 'THiqLu8jgcVRpC2YphgkxLuBE23eFkq31K'
    },
    {
      chain: 'USDC_ERC20',
      userAddressState: 'Ready',
      blockchainAddress: '0xea99ec58006c78fcb01625d2a5466016afd98ac4'
    },
    {
      chain: 'USDT_ERC20',
      userAddressState: 'Ready',
      blockchainAddress: '0xea99ec58006c78fcb01625d2a5466016afd98ac4'
    },
    {
      chain: 'USDT_TRON',
      userAddressState: 'Ready',
      blockchainAddress: 'THiqLu8jgcVRpC2YphgkxLuBE23eFkq31K'
    },
    {
      chain: 'XRP',
      userAddressState: 'Ready',
      blockchainAddress: 'rJ1oJtrSLVBpEM5oMKA8NaBZ7Lp6i5phwT',
      destinationTag: 1153517
    }
  ]
}

400