> For the complete documentation index, see [llms.txt](https://docs.thedex.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thedex.cloud/documentation/invoices/define-invoice-currency.md).

# Define full invoice crypto-currency

<mark style="color:green;">`POST`</mark> `https://app.thedex.cloud/api/v1/invoices/currency`

#### Headers

| Name                                             | Type   | Description                        |
| ------------------------------------------------ | ------ | ---------------------------------- |
| X-EX-APIKEY<mark style="color:red;">\*</mark>    | String | Your API key                       |
| X-EX-PAYLOAD<mark style="color:red;">\*</mark>   | String | Body to base64                     |
| X-EX-SIGNATURE<mark style="color:red;">\*</mark> | String | Encrypted body with the secret key |

#### Request Body

```json
{
    "invoiceId": "String",
    "payCurrency": "String"
}
```

Request **JSON attributes**

| Name                                          | Type   | Description                                                                                                                               |
| --------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| invoiceId<mark style="color:red;">\*</mark>   | String | ID of Invoice for defining                                                                                                                |
| payCurrency<mark style="color:red;">\*</mark> | String | `required` reach out all accessed values by link: [`/api/v1/info/currencies`](/documentation/informational/fetch-currency-definitions.md) |

**Response body**

{% tabs %}
{% tab title="200 defined crypto-currency invoice" %}

```json
{
   "invoiceId": "String",
   "purse": "String",
   "amount": "String",
   "currency": "String",
   "amountInPayCurrency": "String",
   "payCurrency": "String",
   "blockchainFee": "String"
}
```

{% endtab %}

{% tab title="400" %}
General validation error: missing or malformed parameters.

```json
{
    "error": "Bad Request",
    "status": 400,
    "timestamp": "2026-01-01 00:00:00",
    "message": "payCurrency: following value doesn't valid. "
}
```

{% endtab %}

{% tab title="422" %}
Specific field validation error. ([Minimal limits](/introduction/confirmations-and-limits.md), etc)

```json
{
    "error": "Unprocessable Entity",
    "status": 422,
    "timestamp": "2026-01-01 00:00:00",
    "message": "Minimal limit amount doesn't exceed"
}
```

```json
{
    "error": "Unprocessable Entity",
    "status": 422,
    "timestamp": "2026-01-01 00:00:00",
    "message": "Requested payCurrency is not active"
}
```

```json
{
    "error": "Unprocessable Entity",
    "status": 422,
    "timestamp": "2026-01-01 00:00:00",
    "message": "Currency has been applied already"
}
```

{% endtab %}

{% tab title="401" %}
When try to define `payCurrency` for another merchant invoice.

```json
{
    "error": "Unauthorized",
    "status": 401,
    "timestamp": "2026-01-01 00:00:00",
    "message": "Request is not authorized: The requested merchant is not allowed to work with the current invoice"
}
```

{% endtab %}

{% tab title="500" %}
Not found invoice, blockchain or server side problem.

```json
{
    "error": "Internal Server Error",
    "status": 500,
    "timestamp": "2026-01-20 04:16:55",
    "message": "Cannot process pay currency for the invoice"
}
```

{% endtab %}
{% endtabs %}

**Response JSON attributes**

<table data-header-hidden><thead><tr><th width="265"></th><th width="124.33333333333331"></th><th></th></tr></thead><tbody><tr><td><code>"invoiceId"</code></td><td><code>String</code></td><td>Invoice id</td></tr><tr><td><code>"purse"</code></td><td><code>String</code></td><td>Purse</td></tr><tr><td><code>"amount"</code></td><td><code>String</code></td><td>Amount of fiat currency</td></tr><tr><td><code>"currency"</code></td><td><code>String</code></td><td>reach out accessed values by link: <a href="/pages/T8Adh6BIVE4Ma5SN3zSc"><code>/api/v1/info/currencies</code></a></td></tr><tr><td><code>"amountInpayCurrency"</code></td><td><code>String</code></td><td>Amount of cryptocurrency after convertion</td></tr><tr><td><code>"payCurrency"</code></td><td><code>String</code></td><td>reach out accessed values by link: <a href="/pages/T8Adh6BIVE4Ma5SN3zSc"><code>/api/v1/info/currencies</code></a></td></tr><tr><td><code>"blockchainFee"</code></td><td><code>String</code></td><td>Deposit blockchain fee</td></tr></tbody></table>

**Curl request**

```powershell
curl --location --request POST 'https://app.thedex.cloud/api/v1/invoices/currency' \
--header 'X-EX-APIKEY: <string>' \
--header 'X-EX-PAYLOAD: <string>' \
--header 'X-EX-SIGNATURE: <string>' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data '{
  "invoiceId": "<string>",
  "payCurrency": "<string>"
}'
```

**Example Curl**

```powershell
curl --location --request POST 'https://app.thedex.cloud/api/v1/invoices/currency' \
--header 'X-EX-APIKEY: test_api_key_123' \
--header 'X-EX-PAYLOAD: eyJpbnZvaWNlSWQiOiAiSU5WMTIzNDU2IiwgInBheUN1cnJlbmN5IjogIkJUSyJ9' \
--header 'X-EX-SIGNATURE: d4f7e3d2870f18c3c89a1d32aa98e8b5f1a8a9d47ac3b0b0d991b7b5d7d0c0ff' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data '{
  "invoiceId": "INV123456",
  "payCurrency": "BTK"
}'
```

&#x20;