Invoice callbacks
Sent to your callback URL whenever the status of an invoice changes.
Body
Invoice ID.
The foreign_id you provided when creating the invoice.
invoice The currency and amount received for the invoice so far, in the invoice currency, or in the convert_to currency for invoices with automatic conversion. The amount is 0 while nothing has been paid. For partially paid invoices, including failed and cancelled ones, it holds the part of the amount received.
Transactions related to the invoice. The transaction_type field shows what each entry is:
blockchain: an incoming transaction on the blockchaininternal: an incoming transaction for an off-chain payment, which is never sent to the blockchainexchange: the conversion of the payment, present only for invoices with automatic conversion
An invoice can be paid with several transactions (installments), in which case all of them are listed. Once the full amount is received, the invoice is marked as confirmed.
- blockchain
- internal
- exchange
Fees charged for the invoice payment.
The reason the invoice failed. Empty string otherwise. Possible values:
Timer expired. User not paid.: the invoice expired before any payment was received. A payment that arrives after that is listed in a furtherfailedcallback with the same error, and isn't added to your balanceTimer expired. User paid less than requested.: the customer paid less than the required invoice amount before the invoice expiredTimer expired. Transactions were in status processing too long.: a payment was detected but remained in processing for too long without being finalizedCancelled by customer.: the invoice was cancelled via /v2/invoices/{foreign_id}/cancel. A payment already received, in full or in part, isn't added to your balance, even if it's confirmed after the cancellation;currency_receivedandtransactionsshow it
Invoice status:
pending: the invoice has been created and is waiting for payment, or has been partially paid and is waiting for the remaining amount. Until the customer selects a payment currency, the callback has nocrypto_addressandcurrency_sent. An invoice with a timer sends its firstpendingcallback when it's created; an invoice without a timer sends no callback until the customer selects a payment currency, or until it's cancelledconfirmed: the invoice has been paid in full, with one or several transactions, or it is a partial pay invoice (good_until_expired) that expired after a partial payment and is confirmed for the amount received. It can be treated as completed on your sideprocessing: the full amount has been detected but the payment has not yet been finalized, for example a transaction in the mempool. Treat the invoice as pending until you receive theconfirmedcallbackfailed: the invoice was not paid and will not be completed. Use theerrorfield to determine the reason
pending, confirmed, processing, failed Unix time in seconds when the rate was fixed: the creation time for invoices created with sender_currency, otherwise when the customer selected a payment currency. null until then, including in the callback for an invoice cancelled before that.
Unix time in seconds when the invoice expires. null for an invoice without a timer until the customer selects a payment currency, including in the callback for an invoice cancelled before that. Once the full amount is detected (the processing callback), it moves to 24 hours after that payment. A partial payment doesn't move it.
The end_user_reference you provided when creating the invoice.
Details of the address the customer pays to. Absent until a payment currency is set (at creation with sender_currency, or when the customer selects one), including in the callback for an invoice cancelled before that.
The invoice amount in the payment currency. Absent until a payment currency is set (at creation with sender_currency, or when the customer selects one), including in the callback for an invoice cancelled before that. When a partial pay invoice is confirmed after expiring with a partial payment, amount shows the amount paid.