> For the complete documentation index, see [llms.txt](https://docs.cryptobox.ninja/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cryptobox.ninja/deposits/deposit-tracking-session.md).

# Deposit Tracking Session

## A Sample Code For Creating A Deposit Tracking Session

Below, you can find an example of how to create a deposit tracking session using TypeScript code. With our infrastructure, customers can track deposits and monitor their status as they progress through various stages. 

{% code fullWidth="false" %}

```typescript
import {createHmac} from 'crypto';

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

const payloadPgCreateSessionForAUser = {
    userId: 'YOUR_UNIQUE_USER_ID',
    userName: 'YOUR_USER_NAME',
    userNameSurname: 'THE_NAME_AND_SURNAME_OF_YOUR_USER',
    sessionDefaultLanguage: 'en',
    sessionDefaultFiatCurrency: 'USD',
    minPaymentAmountInUSD: 0.5
};

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

try {
    const sessionCreationResult = await axios.post(
        'https://api-prod.alfa-instap-cpt.uk/pgpub/session', 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');
}


```

{% endcode %}

## Creating A Deposit Tracking Session API Endpoint

{% hint style="warning" %}
To ensure that your POST requests are handled correctly, follow these steps:\
Firstly, convert the request body to a string using JSON.stringify(). \
Then, calculate the x-payload-hash based on this stringified body and pass it on to the **x-payload-hash** header. \
Additionally, use the same stringified body while making the POST request and ensure that the HMAC payload is base 64 encoded. \
\
It's crucial to examine the sample code carefully to ensure that these steps are implemented correctly. Failing to complete these steps will result in your request being rejected with an error code of errorHmacDoesNotMatch.
{% endhint %}

<mark style="color:green;">`POST`</mark> `https://api-prod.alfa-instap-cpt.uk/pgpub/session`

**Session Token** and **Operation No** mean the same thing for our system. Before tracking your users' deposits, you need to create a deposit-tracking session. The system associates this session with a session token. The system manages session tokens.

#### Headers

| Name                                             | Type   | Description                                                                                   |
| ------------------------------------------------ | ------ | --------------------------------------------------------------------------------------------- |
| content-type<mark style="color:red;">\*</mark>   | string | application/json                                                                              |
| x-api-key<mark style="color:red;">\*</mark>      | string | **Replace your API key**                                                                      |
| x-payload-hash<mark style="color:red;">\*</mark> | string | **Replace your calculated HMAC hash.** [**See API Security**](/security/api-security.md)**.** |

#### Request Body

| Name                                       | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| userId<mark style="color:red;">\*</mark>   | 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. <mark style="color:blue;">**userId**</mark> <mark style="color:blue;"></mark><mark style="color:blue;">parameter must be</mark> <mark style="color:blue;"></mark><mark style="color:blue;">**unique**</mark> <mark style="color:blue;"></mark><mark style="color:blue;">within the customer's infrastructure.</mark> |
| userName<mark style="color:red;">\*</mark> | string | STRING \[Min 1,Max 4000] Characters This parameter is for display only, and the system does not use this parameter while tracking deposit events.                                                                                                                                                                                                                                                                                                                                                                       |
| userNameSurname                            | string | STRING \[Min 1,Max 4000] Characters This parameter is for display only, and the system does not use this parameter while tracking deposit events.                                                                                                                                                                                                                                                                                                                                                                       |
| userEmail                                  | string | STRING \[Min 1,Max 4000] Characters This parameter is for display only, and the system does not use this parameter while tracking deposit events.                                                                                                                                                                                                                                                                                                                                                                       |
| maxPaymentAmountInUSD                      | number | <p>NUMBER The system uses this parameter to set the state of the deposit. The state of the deposit can be overpaid, underpaid or correct. </p><p><mark style="color:orange;">This parameter can not be less than zero or smaller than <strong>minPaymentAmountInUSD</strong>.</mark> </p><p>The default value of this parameter is 5000$.</p>                                                                                                                                                                           |
| minPaymentAmountInUSD                      | number | <p>NUMBER The system uses this parameter to set the state of the deposit. The state of the deposit can be overpaid, underpaid or correct. </p><p><mark style="color:orange;">This parameter can not be less than zero or bigger than <strong>maxPaymentAmountInUSD</strong>.</mark></p><p>If the customer sets this parameter, the system initializes the minimum payment for this amount. If the customer bypasses this parameter, the system uses the system's default which is 10$.</p>                              |
| sessionDefaultFiatCurrency                 | string | <p>STRING 3 Characters<br>If the customer sets this parameter, the system initializes the session for this fiat currency. If the customer bypasses this parameter, the system selects USD as the initial currency of the session. Your users can change this parameter during the checkout process, and the client code of the checkout page will make the necessary conversions.</p>                                                                                                                                   |
| sessionDefaultLanguage                     | string | <p>STRING 2 Characters<br>The system activates the checkout page for this language. If not present, the checkout page will use the system's default session language.</p>                                                                                                                                                                                                                                                                                                                                               |
| redirectUrl                                | string | Upon completion of the deposit tracking session, this field specifies the exact web address to which the user will be automatically redirected. ***The URL provided should be accessible and lead to the appropriate destination for a seamless user experience.***                                                                                                                                                                                                                                                     |

{% tabs %}
{% tab title="200 Success" %}
The system successfully creates the deposit tracking session.

```json
{
    "sessionToken": "Operation No",
    "checkOutUrl": "Redirect URL of your user's checkout page"
}
```

{% endtab %}

{% tab title="400: Bad Request errorHmacNotActiveForTheUser" %}
If HMAC security is not activated for the user, the system will reject the request. Please see [enabling HMAC](/security/enable-update-hmac.md).
{% endtab %}

{% tab title="400: Bad Request payloadDoesNotComply" %}
If the validation fails for the payload, the system will return this error code as a response containing the invalid parameter.
{% endtab %}

{% tab title="400: Bad Request errorHmacDoesNotMatch" %}
The customers must sign the body of this request with their HAMC secret. To compare the **x-payload-hash**, our system also signs the same request payload with the customer's HMAC secret. The system will return this error code if the calculated payload does not match the system's computed hash. Please see the [API Security](/security/api-security.md) section.
{% endtab %}
{% endtabs %}

## Querying The Deposit Tracking Session API Endpoint

{% hint style="danger" %}
You can use this endpoint to fetch a straightforward report for a deposit session token *at a later time*. **It is important to note that customers are not required to query this endpoint immediately after receiving a** [**deposit event**](/deposits/deposit-events.md) **notification.** \
This endpoint provides a convenient way to report a deposit session token.\
\
When a deposit is made, it triggers a [deposit notification](/deposits/deposit-events.md), providing all the required information related to the incoming transaction. This notification is designed to give you a clear understanding of the final outcome of the deposit, including the amount of cryptocurrency deposited by your user, the date and time of the blockchain transaction, and all the other essential details. By relying on this notification, you can be confident that you have accurate and up-to-date information about your deposit, and you can take any necessary action based on that information.
{% endhint %}

<mark style="color:blue;">`GET`</mark> `https://api-prod.alfa-instap-cpt.uk/pgpub/session/{sessionToken}`

One can learn about the state of the deposit tracking session using this endpoint.

#### Query Parameters

| Name                                           | Type   | Description                     |
| ---------------------------------------------- | ------ | ------------------------------- |
| sessionToken<mark style="color:red;">\*</mark> | string | The session token to be queried |

#### Headers

| Name                                           | Type   | Description              |
| ---------------------------------------------- | ------ | ------------------------ |
| content-type<mark style="color:red;">\*</mark> | string | application/json         |
| x-api-key<mark style="color:red;">\*</mark>    | string | **Replace your API key** |

{% tabs %}
{% tab title="200: OK Success" %}

```json
{
    "sessionState": "The state of the session",
    "checkOutUrl": "The checkout page of the session"
}
```

The status of the session will be one of the following.

**NEW**: This state means the system successfully creates a new payment gateway session.

**COMPLETED**: This state indicates that the system detects a completed blockchain transaction.&#x20;

**EXPIRED**: This state means that the payment gateway session has expired without any deposit event.

**FAILED**: This state suggests the system abnormally terminated the payment gateway session. It can only occur if the system does not push the event to our event source.
{% endtab %}

{% tab title="400: Bad Request pubApiHeadersNotValid" %}
The x-api-key header must exist on the HTTP headers of the request.
{% endtab %}

{% tab title="400: Bad Request customerNotFoundFromApiKey" %}
The system will return this error code if the API key does not correspond to a customer.
{% endtab %}
{% endtabs %}