> 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/withdrawals/withdrawal-session.md).

# Withdrawal Session

## Creating A Withdrawal Request API Endpoint

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

Customers create withdrawal requests in fiat currency. After validations, the incoming withdrawal request is informed to the financial administrator.&#x20;

#### 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                                                                                                                                                                                                           |
| ----------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| withdrawRequestId<mark style="color:red;">\*</mark>   | string | <p>The system activates the withdrawal session for this id.<br>This id must be unique. If the customer sends the same withdrawRequestId for different withdrawal requests, the system will reject those requests.</p> |
| withdrawRequestDate<mark style="color:red;">\*</mark> | number | This field represents the current epoch time in milliseconds.                                                                                                                                                         |
| userId<mark style="color:red;">\*</mark>              | string | \[Min 1,Max 4000] Characters The customer creates the withdrawal request for this user id.                                                                                                                            |
| userName<mark style="color:red;">\*</mark>            | string | \[Min 1,Max 4000] Characters The customer creates the withdrawal request for this user name.                                                                                                                          |
| fiatCurrency<mark style="color:red;">\*</mark>        | string | This field represents the fiat currency. The customers create the withdrawal requests by the fiat currency. The system converts the fiat currency to the corresponding crypto currency.                               |
| fiatAmount<mark style="color:red;">\*</mark>          | number | This field represents the fiat amount. The customers create the withdrawal requests by the fiat currency. The system converts the fiat amount to the corresponding crypto currency.                                   |
| currency<mark style="color:red;">\*</mark>            | string | This field represents the crypto-currency code for the withdrawal. **Crypto-currency codes** and **supported chains/tokens** can be found [here](/welcome-to-cryptobox-ninja.md).                                     |
| toAddress<mark style="color:red;">\*</mark>           | string | toAddress is the target blockchain address, where the system sends the amount after approval.                                                                                                                         |
| destinationTag                                        | string | When the customers need to request an XRP coin, they can fill this field. Some XRP accounts can only work with destination tag.                                                                                       |

{% tabs %}
{% tab title="200: OK Success" %}
When all the validations have passed, and the system informs the withdrawal request to the financial administrator, the system responds with a 200. The response includes the details of the fiat-to-cryptocurrency conversion.

```json
{
  withdrawRequestId: '',
  withdrawRequestToBePersisted: {
    userId: '',
    toAddress: '',
    currency: '',
    fiatCurrency: '',
    fiatAmount: 0.0,
    userName: '',
    withdrawRequestId: '',
    withdrawRequestDate: EPOCH,
    amount: 0.0,
    fiatToCryptoConversionResult: {
      fiatCurrency: '',
      fiatAmount: 0.0,
      cryptoCurrency: '',
      conversionEpochTime: EPOCH,
      rate: '',
      cryptoAmount: 0.0
    }
  }
}
```

{% 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. For comparing 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 %}

{% tab title="400: Bad Request toAddressSecurityCheckInvalidAddress" %}
The system checks the target address against a well-known malicious address list. This check is limited to BTC and LTC. A malicious address can contain assets from the DarkWeb, is connected to scam projects, or has stolen funds. If the address is not valid, this error code is returned.
{% endtab %}

{% tab title="400: Bad Request withdrawRequestIdHasBeenProcessedBefore" %}
The system responds with this error code if the customer's endpoint sends the same withdrawRequestId for different withdrawal requests.
{% endtab %}

{% tab title="400: Bad Request trc20WithdrawAmountIsBiggerThanTheSystemBalance" %}
If the withdrawal amount is bigger than the total balance of the system, the system returns this error code.
{% endtab %}

{% tab title="400: Bad Request withdrawAmountCanNotBeBiggerThanCustomerAccountBalance" %}
Each customer can create a withdrawal request according to their total available balance. The system will return this error code if the withdrawal request amount exceeds the customer's available balance.
{% endtab %}

{% tab title="400: Bad Request wdRequestProcessStopsConfigurationOff" %}
This error code shows that the system administrators recently switched off the withdrawal functionality.
{% endtab %}
{% endtabs %}

## Query The Withdrawal Request API Endpoint

{% hint style="danger" %}
You can use this endpoint to fetch a very simple report for a withdrawal session token *at a later time*. **It is important to note that customers are not required to query this endpoint immediately after receiving a** [**withdrawal event**](/withdrawals/withdrawal-events.md) **notification.** \
\
When a withdrawal event occurs, it triggers a [withdrawal event](/withdrawals/withdrawal-events.md) notification that provides all the necessary information about the transaction. This notification is designed to give you a clear understanding of the final outcome of the withdrawal, including the amount of cryptocurrency that was withdrawn, the date and time of the transaction, and any other relevant details. By relying on this notification, you can be confident that you have accurate and up-to-date information about your withdrawal, 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/wdreqpub/wdrequest/{withdrawRequestId}`

This endpoint is for manually querying the withdrawal state. It can also be used to learn about the withdrawal process. **The withdraw event object, which the system sends upon a withdrawal, is enough for standard operations.**

#### Path Parameters

| Name                                                | Type   | Description                              |
| --------------------------------------------------- | ------ | ---------------------------------------- |
| withdrawRequestId<mark style="color:red;">\*</mark> | string | The withdrawal request id 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" %}
The status of the withdrawal will be one of the following:

**NEW**: This state means the system successfully creates a new withdrawal request.&#x20;

**COMPLETED**: The system completes the withdrawal and the job sends the assets to the target blockchain address. If the withdrawal state is COMPLETED, the system will fill in the txId field.&#x20;

**PROCESSING**: If the financial administrator of the system approves the withdrawal request, the system will push the withdrawal request to our FIFO queue. This state means that the request is pushed to the queue and the system processes the request.&#x20;

**FAILED**: This state suggests the system encounters an error while processing the withdrawal request.&#x20;

**REJECTED**: This state suggests that the financial administrator rejects the withdrawal request.

```json
{
    "withdrawalState": "WITHDRAWAL STATE",
    "txId": "The blockchain transaction id",
    "callbackSuccess": true,
    "amount": 0.0,
    "currency": "",
    "userId": "",
    "withdrawTime": EPOCH(),
    "userName": "",
    "operationNo": ""
}
```

{% endtab %}
{% endtabs %}