# Create quick crypto invoice

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

#### Headers

<table><thead><tr><th>Name</th><th width="179">Type</th><th>Description</th></tr></thead><tbody><tr><td>X-EX-APIKEY<mark style="color:red;">*</mark></td><td>String</td><td>Your API key</td></tr><tr><td>X-EX-PAYLOAD<mark style="color:red;">*</mark></td><td>String</td><td>Body to base64</td></tr><tr><td>X-EX-SIGNATURE<mark style="color:red;">*</mark></td><td>String</td><td>Encrypted body with the secret key</td></tr></tbody></table>

#### Request Body

```json
{
    "amount": "Number",
    "payCurrency": "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 
    "generateQr": "String"      // optional 
}
    
```

**Request JSON attributes**

<table><thead><tr><th width="152">Name</th><th width="132">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:<br><code>api/v1/info/invoice/limit/crypto</code></td></tr><tr><td>payCurrency<mark style="color:red;">*</mark></td><td>String</td><td>Reach out all available crypto 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><p>Merchant ID</p><p>You can find it on page 'Merchants' in your account</p></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>Used as additional details for invoice.<br>Or <code>required</code> in couple with field <code>"needsEmailConfirmation"</code>.<br>In the second case, this email will receive confirmation link, necessary  to get access to <a href="define-invoice-currency">“Define invoice currency”</a> mentioned in <a href="broken-reference">"<strong>Steps to complete and read the invoice using email</strong> confirmation<strong>".</strong></a></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><tr><td>generateQr</td><td>String</td><td><p></p><p><strong>QR Code Generation Modes</strong>:</p><ul><li><strong>NONE</strong> (default): No QR code will be generated.</li><li><strong>ADDRESS</strong>: Generates a QR code with the pure address.</li><li><strong>FULL_PAYMENT</strong>: This feature generates a QR code with options like network switching, contract details, and amount prefilling. It generally works best with ETH-like or BTC-like networks but may vary elsewhere. For example, TRON often only supports basic addresses. TON payments are well supported in Tonkeeper and MyTonWallet, though Trust may not handle them properly..</li><li><strong>PAYMENT_URL</strong>: Generates a QR code that is a link to payment</li></ul></td></tr></tbody></table>

**Response body:**

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

```json
{
   "invoiceId": "String",
   "merchantId": "String",
   "clientId": "String",
   "orderId": "String",
   "purse": "String",
   "payCurrency": "String",
   "blockchainFee": "String",
   "amount": "String",
   "amountInPayCurrency": "String",
   "createDate": "String",
   "modifiedDate": "String",
   "createTimestamp": "Long",
   "modifiedTimestamp": "Long",
   "expirationTimestamp": "Long",
   "status": "Integer",
   "payUrl": "String",
   "qrUrl": "String",
   "qrBase64": "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](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="272"></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>"purse"</code></td><td><code>String</code></td><td>Purse (crypto wallet)</td></tr><tr><td><code>"payCurrency"</code></td><td><code>String</code></td><td>Pay currency (crypto currency)</td></tr><tr><td><code>"blockchainFee"</code></td><td><code>String</code></td><td>Deposit blockchain fee</td></tr><tr><td><code>"amountInPayCurrency"</code></td><td><code>String</code></td><td>Amount in crypto currency</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>Modification 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>"qrBase64"</code></td><td><code>String</code></td><td><p>Optional </p><p>QR base64-encoded image of the QR code</p></td></tr><tr><td><code>"qrUrl"</code></td><td><code>String</code></td><td>Optional<br>Link to the QR image</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:**&#x20;

```powershell
curl --location --request POST 'https://app.thedex.cloud/api/v1/invoices/create/quick/crypto' \
--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>",
  "payCurrency": "<string>",
  "description": "<string>",
  "email": "<string>",
  "merchantId": "<string>",
  "orderId": "<string>",
  "recalculation": "<boolean>",
  "unfixAmount": "<boolean>",
  "title": "<string>",
  "successUrl": "<string>",
  "failureUrl": "<string>",
  "callbackUrl": "<string>",
  "returnUrl": "<string>",
  "generateQr": "<string>"
}'
```

**Example Curl**

```powershell
curl --location --request POST 'https://app.thedex.cloud/api/v1/invoices/create/quick/crypto' \
--header 'X-EX-APIKEY: test_api_key_123' \
--header 'X-EX-PAYLOAD: eyJhbW91bnQiOjEwMCwiY2xpZW50SWQiOiJjbGllbnRfMDEiLCJwYXlDdXJyZW5jeSI6IkJUQyIsImRlc2NyaXB0aW9uIjoiU29tZSB0ZXN0IGRlc2NyaXB0aW9uIiwiZW1haWwiOiJ0ZXN0QGVtYWlsLmNvbSIsIm1lcmNoYW50SWQiOiJNQ0hfMTIzIiwiY2FsbGJhY2tVcmwiOiJodHRwczovL3d3dy5leGFtcGxlLmNvbS9jYWxsYmFjayIsIm9yZGVySWQiOiJPUkRfMDAxIiwicmVjYWxjdWxhdGlvbiI6ZmFsc2UsInVuZml4QW1vdW50IjpmYWxzZSwidGl0bGUiOiJUZXN0IEludm9pY2UiLCJzdWNjZXNzVXJsIjoiaHR0cHM6Ly93d3cuZXhhbXBsZS5jb20vc3VjY2VzcyIsImZhaWx1cmVVcmwiOiJodHRwczovL3d3dy5leGFtcGxlLmNvbS9mYWlsdXJlIn0=' \
--header 'X-EX-SIGNATURE: f5c614aa0b75d9b2b1d5d63c2be74c8d0914e48c89ac21a1dc2597d2577a8aab' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data '{
  "amount": 100,
  "clientId": "client_01",
  "payCurrency": "BTC",
  "description": "Some test description",
  "email": "test@email.com",
  "merchantId": "MCH_123",
  "orderId": "ORD_001",
  "recalculation": false,
  "unfixAmount": false,
  "title": "Test Invoice",
  "successUrl": "https://www.example.com/success",
  "failureUrl": "https://www.example.com/failure",
  "callbackUrl": "https://www.example.com/callback",
  "returnUrl": "https://www.example.com/return",
  "generateQr": "FULL_PAYMENT"
}'
```