# Create full invoice

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

#### 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

{% code overflow="wrap" %}

```json
{
    "amount": "Number",
    "currency": "String",
    "merchantId": "String",
    "orderId": "String",        // optional 
    "email": "String",          // optional 
    "clientId": "String",       // optional 
    "title": "String",          // optional 
    "description": "String",    // optional 
    "recalculation": "boolean", // optional 
    "successUrl": "String",     // optional 
    "failureUrl": "String",     // optional 
    "callbackUrl": "String",    // optional 
    "returnUrl": "String",      // optional 
    "unfixAmount": "boolean"    // optional 
}
```

{% endcode %}

**Request JSON attributes**

<table><thead><tr><th>Name</th><th width="205">Type</th><th>Description</th></tr></thead><tbody><tr><td>amount<mark style="color:red;">*</mark></td><td>BigDecimal</td><td>To check minimal limit amount, use:<a href="../informational/fetch-fiat-limits-in-invoices"><br><code>api/v1/info/invoice/limit/fiat</code></a></td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>String</td><td>Reach out all available fiat currencies by endpoint: <a href="../informational/fetch-currency-definitions"><code>/api/v1/info/currencies</code></a></td></tr><tr><td>merchantId<mark style="color:red;">*</mark></td><td>String</td><td>Merchant ID <br>You can find it on page 'Merchants' in your account</td></tr><tr><td>orderId</td><td>String</td><td>Order ID in your system</td></tr><tr><td>email</td><td>String</td><td>email of your client</td></tr><tr><td>clientId</td><td>String</td><td>ID of your client</td></tr><tr><td>title</td><td>String</td><td><code>max size = 50</code></td></tr><tr><td>description</td><td>String</td><td><code>max size = 300</code></td></tr><tr><td>recalculation</td><td>boolean</td><td><p><strong>Default = false</strong> </p><p></p><p>If <code>recalculation = false</code>,  the invoice will be expecting a payment that is equal to or greater than 'amountInPayCurrency'</p><p>'amountInPayCurrency' and 'merchantBalance' of invoice <strong>will not be</strong> recalculated in the case of </p><p><code>Successful</code>status. If client send amount that less than 'amountInPayCurrency' status of invoice will be <code>Underpaid</code></p><p><br>If <code>recalculation = true</code>, the invoice will be expecting a payment that is equal to or greater than 'amountInPayCurrency'</p><p>'amountInPayCurrency' and 'merchantBalance' of invoice <strong>will  be recalculated</strong> in the case of </p><p><code>Successful</code>status. If the client send amount that is less than 'amountInPayCurrency' status of invoice will be <code>Underpaid</code></p><p></p><p><br>Reach out all available invoice statuses by endpoint:</p><p><a href="../informational/fetch-status-definitions"><code>/api/v1/info/statuses</code></a></p></td></tr><tr><td>successUrl</td><td>String</td><td>Custom successUrl for an invoice, that can be differ from merchant settings</td></tr><tr><td>failureUrl</td><td>String</td><td>Custom failureUrl for an invoice, that can be differ from merchant settings</td></tr><tr><td>callbackUrl</td><td>String</td><td>Custom callbackUrl for an invoice, that can be differ from merchant settings</td></tr><tr><td>returnUrl</td><td>String</td><td>Custom returnUrl for an invoice, that can be differ from merchant settings. Rewrites merchantSiteUrl for invoice</td></tr><tr><td>unfixAmount</td><td>boolean</td><td><p><strong>Default = false</strong> </p><p></p><p>If <code>unfixAmount = true</code>, the amount of the invoice will be unfixed, so the client can send any amount, and 'amountInPayCurrency'  will be recalculated.<br>In this case, only one transaction is allowed to pay.</p><p></p><p>If <code>unfixAmount = true</code>, the flow of processing invoice will be as <code>recalculation</code> parameter setting</p></td></tr></tbody></table>

**Response body**

{% tabs %}
{% tab title="200 created invoice" %}

```json
{
   "invoiceId": "String",
   "merchantId": "String",
   "clientId": "String",
   "orderId": "String",
   "createDate": "String",
   "modifiedDate": "String",
   "createTimestamp": "Long",
   "modifiedTimestamp": "Long",
   "expirationTimestamp": "Long",
   "amount": "String",
   "currency": "String",
   "status": "Integer",
   "payUrl": "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": "currency: following value doesn't valid. "
}
```

{% endtab %}

{% tab title="422" %}
Specific field validation error. ([Minimal limits](https://docs.thedex.cloud/introduction/confirmations-and-limits), 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"
}
```

{% endtab %}

{% tab title="403" %}
In case of not existing parameters, incorrect headers, etc..

```json
Empty response
```

{% endtab %}

{% tab title="401" %}
When `merchantId` in request not equal to API key merchant id

```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 this API key"
}
```

{% endtab %}

{% tab title="500" %}
Blockchain or server side problem.

```json
{
    "error": "Internal Server Error",
    "status": 500,
    "timestamp": "2026-01-01 00:00:00",
    "message": "Cannot create invoice"
}
```

{% endtab %}
{% endtabs %}

\
**Response JSON attributes**

<table data-header-hidden><thead><tr><th width="269"></th><th width="130.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>"merchantId"</code></td><td><code>String</code></td><td>Merchant Id</td></tr><tr><td><code>"orderId"</code></td><td><code>String</code></td><td>Order id</td></tr><tr><td><code>"clientId"</code></td><td><code>String</code></td><td>Client id</td></tr><tr><td><code>"createDate"</code></td><td><code>String</code></td><td>Creation date</td></tr><tr><td><code>"modifiedDate"</code></td><td><code>String</code></td><td>Modification date</td></tr><tr><td><code>"createTimestamp"</code></td><td><code>Long</code></td><td>Creation date in milliseconds</td></tr><tr><td><code>"modifiedTimestamp"</code></td><td><code>Long</code></td><td>Modified date in milliseconds</td></tr><tr><td><code>"expirationTimestamp"</code></td><td><code>Long</code></td><td>Expiration date in milliseconds</td></tr><tr><td><code>"status"</code></td><td><code>Integer</code></td><td>reach out all accessed values by link: <a href="../informational/fetch-status-definitions"><code>/api/v1/info/statuses</code></a></td></tr><tr><td><code>"payUrl"</code></td><td><code>String</code></td><td>Pay Url</td></tr><tr><td><code>"amount"</code></td><td><code>"String"</code></td><td>Amount to Pay in Fiat currency</td></tr></tbody></table>

**Curl request**

```powershell
curl --location --request POST'https://app.thedex.cloud/api/v1/invoices/create' \
--header 'X-EX-APIKEY: <string>' \
--header 'X-EX-PAYLOAD: <string>' \
--header 'X-EX-SIGNATURE: <string>' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data '{
  "amount": "<number>",
  "clientId": "<string>",
  "currency": "<string>",
  "description": "<string>",
  "email": "<string>",
  "merchantId": "<string>",
  "orderId": "<string>",
  "recalculation": "<boolean>",
  "unfixAmount": "<boolean>",
  "title": "<string>",
  "successUrl": "<string>",
  "failureUrl": "<string>",
  "callbackUrl": "<string>",
  "returnUrl": "<string>"
}'
```

Example Curl

```powershell
curl --location --request POST 'https://app.thedex.cloud/api/v1/invoices/create' \
--header 'X-EX-APIKEY: abc123apikeyxyz' \
--header 'X-EX-PAYLOAD: eyJhbW91bnQiOjEwLCJjdXJyZW5jeSI6IlVTRCJ9' \
--header 'X-EX-SIGNATURE: a5f67a9b8e0cdfe0df8be6e5f0a83cb5f2d3a9341d0fce6...' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data '{
    "amount": 10,
    "currency": "USD",
    "merchantId": "YDRE5IDM",
    "orderId": "1",
    "email": "test@example.com",
    "clientId": "1",
    "title": "Test_Title",
    "description": "Test description",
    "recalculation": "false", 
    "successUrl": "https://www.google.com/200",
    "failureUrl": "https://www.google.com/404", 
    "callbackUrl": "https://www.google.com",
    "returnUrl": "https://www.google.com/return", 
    "unfixAmount": "false" 
}'

```