> 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/introduction/callback/invoice.md).

# Invoice

#### 📡**Invoice Callbacks (Webhooks)**

These are **server-side callbacks** sent to the merchant's server whenever the status of **invoice** changes.

**Invoice Callback**

* Triggered when:
  * The invoice is successfully paid 
  * The invoice expires
  * The invoice is canceled
  * The invoice is rejected
  * The invoice is underpaid 
  * The invoice is paid twice
  * The invoice is paid in another currency
* The callback sends the **updated invoice data** (e.g., status, amount, currency) to the configured `callbackUrl`.

#### **Callback body example**

{% tabs %}
{% tab title="Successful invoice" %}
**Invoice callback structure notes**

* The **set and number of fields may vary** depending on the invoice type (**Full invoice** or **Quick invoice**).
* Not all fields are guaranteed to be present for every invoice type.
* Transitions to **Rejected** and **Cancelled** statuses can be performed by the support team.

```json
{
  "invoiceId": "e70f075f-e858-4cb2-9062-a20ca1fa4c92",
  "merchantId": "ABCDEFGH",
  "status": 3,
  "statusName": "Successful",
  "createDate": "2025-11-27 17:11:30.19",
  "modifiedDate": "2025-11-27 20:47:03.252",
  "expirationDate": "2025-11-27 19:11:30.014",
  "createTimestamp": 1764256290190,
  "modifiedTimestamp": 1764269223252,
  "expirationTimestamp": 1764263490014,
  "expirationDateInMilliseconds": 0,
  "purse": "0x0000000000000000000000000000000000000000",
  "currency": "USD",
  "payCurrency": "ETH_ETHEREUM",
  "amount": "0.00",
  "amountInPayCurrency": "1",
  "paidAmount": "1",
  "paidAmountFiat": "2500",
  "payUrl": "https://app.thedex.cloud/pay-invoice/e70f075f-e858-4cb2-9062-a20ca1fa4c92",
  "creationWay": "API",
  "merchantCommission": "0",
  "merchantBalance": "0.9995",
  "uniqueUserId": "SQCGMWJZ",
  "depositBlockchainFee": "0.0005",
  "rate": "2500.00",
  "rateWithCommission": "2500.00",
  "txId": [
    "0x00000000000000000000000000000000000000000000"
  ],
  "fromAddress": [
    "0x10000000000000000000000000000000000000000000"
  ],
```

{% endtab %}

{% tab title="Unsuccessful" %}
**Unsuccessful invoices**

An **unsuccessful invoice** can be in one of the following three statuses:

* **Unpaid**
* **Rejected**
* **Cancelled**

**Unpaid**

An invoice has the **Unpaid** status when it was created but **no successful payment was made** before the expiration time.

**Rejected**

An invoice receives the **Rejected** status in the following cases:

* The invoice was **manually rejected by the support team** when required.
* The payment was made using funds with a **high risk score**, as determined by AML (Anti-Money Laundering) checks.

In such cases, the payment is not accepted and the invoice is marked as rejected.

**Cancelled**

An invoice can be moved to the **Cancelled** status **manually by the support team** when necessary (for example, due to operational or compliance reasons).

```json
{
  "invoiceId": "e70f075f-e858-4cb2-9062-a20ca1fa4c92",
  "merchantId": "ABCDEFGH",
  "status": 2,
  "statusName": "Unpaid",
  "createDate": "2025-11-27 17:11:30.19",
  "modifiedDate": "2025-11-27 20:47:03.252",
  "expirationDate": "2025-11-27 19:11:30.014",
  "createTimestamp": 1764256290190,
  "modifiedTimestamp": 1764269223252,
  "expirationTimestamp": 1764263490014,
  "expirationDateInMilliseconds": 0,
  "purse": "0x0000000000000000000000000000000000000000",
  "currency": "USD",
  "payCurrency": "ETH_ETHEREUM",
  "amount": "0.00",
  "amountInPayCurrency": "1",
  "payUrl": "https://app.thedex.cloud/pay-invoice/e70f075f-e858-4cb2-9062-a20ca1fa4c92",
  "creationWay": "API",
  "merchantCommission": "0",
  "merchantBalance": "0.9995",
  "uniqueUserId": "SQCGMWJZ",
  "depositBlockchainFee": "0.0005",
  "rate": "2500.00",
  "rateWithCommission": "2500.00",
  "txId": [],
  "fromAddress": [],
  "successUrl": "https://google.com/",
  "failureUrl": "https://google.com/",
  "merchantSiteUrl": "https://google.com/",
  "callbackUrl": "https://webhook.site/",
  "complexCommission": "0"
}
```

{% endtab %}

{% tab title="Double Paid/Another Currency" %}
The key difference between **Double Paid** and **Another Currency** invoices is defined by the `creationWay` field.

**Double Paid invoices**

A **Double Paid** invoice is created when the **successful invoice is paid more than once** in the same currency.\
In this case:

* The invoice is generated as a result of a duplicate payment.
* The **currency of the invoice is always the same as the original invoice**.
* The invoice is directly linked to the original one via `parentInvoiceId`.

**Another Currency invoices**

An **Another Currency** invoice is created when an invoice is paid **in a different currency than the original invoice currency**.\
In this case:

* The invoice is generated due to a currency mismatch during payment.
* The **invoice currency may differ from the currency of the original (parent) invoice**.
* The relationship with the original invoice is maintained via `parentInvoiceId`.

```json
{
  "invoiceId": "e70f075f-e858-4cb2-9062-a20ca1fa4c92",
  "merchantId": "ABCDEFGH",
  "status": 3,
  "statusName": "Successful",
  "createDate": "2025-11-27 17:11:30.19",
  "modifiedDate": "2025-11-27 20:47:03.252",
  "expirationDate": "2025-11-27 19:11:30.014",
  "createTimestamp": 1764256290190,
  "modifiedTimestamp": 1764269223252,
  "expirationTimestamp": 1764263490014,
  "expirationDateInMilliseconds": 0,
  "purse": "0x0000000000000000000000000000000000000000",
  "currency": "USD",
  "payCurrency": "ETH_ETHEREUM",
  "amount": "0.00",
  "amountInPayCurrency": "1",
  "paidAmount": "1",
  "paidAmountFiat": "2500",
  "payUrl": "https://app.thedex.cloud/pay-invoice/e70f075f-e858-4cb2-9062-a20ca1fa4c92",
  "creationWay": "DOUBLE_PAY/ANOTHER_CURRENCY",
  "merchantCommission": "0",
  "merchantBalance": "0.9995",
  "description": "",
  "uniqueUserId": "SQCGMWJZ",
  "depositBlockchainFee": "0.0005",
  "rate": "2500.00",
  "rateWithCommission": "2500.00",
  "txId": [
    "0x00000000000000000000000000000000000000000000"
  ],
  "fromAddress": [
    "0x10000000000000000000000000000000000000000000"
  ],
  "successUrl": "https://google.com/",
  "failureUrl": "https://google.com/",
  "merchantSiteUrl": "https://google.com/",
  "callbackUrl": "https://webhook.site/",
  "complexCommission": "0",
  "parentInvoiceId": "6dfb5dba-749e-4a4b-8416-a17b0bce73f7"
}
```

{% endtab %}
{% endtabs %}

**Notes:**

* These callbacks enable your server to automatically update the order/payment status based on real-time data from TheDex.
* Callbacks can be **manually re-sent** from the **admin panel** in case of delivery failure or testing purposes.
* For testing callback URLs, services like <https://webhook.site/> can be used.