Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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.

{
  "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"
  ],

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).

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.

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.

PreviousCallbackNextPayout

Last updated