Invoice Status Callback

Overview

Meaning in plain language

Invoice status callback is the authenticated webhook message sent to a merchant when the state of an invoice or associated payment changes. The callback normally includes invoice or track identifiers, order reference, status, amounts, asset and network data, and transaction details.

How it works

The callback normally includes invoice or track identifiers, order reference, status, amounts, asset and network data, and transaction details. Providers may retry delivery until the merchant returns the expected acknowledgment.

Merchants should verify authenticity, process events idempotently, tolerate out-of-order delivery, query current status when necessary, and store the raw payload and processing result. Status callbacks should trigger controlled state transitions rather than direct unvalidated database updates.

The callback message is distinct from the callback URL, which is the endpoint configuration, and from a browser success redirect, which is not a reliable proof of payment.

When an invoice moves from paying to paid, the merchant can receive two callbacks and update the order only when the paid event passes signature and consistency checks.

Where people get it wrong

A callback is a notification, not authority to skip reconciliation. Handle retries, duplicated deliveries, out-of-order updates and an unavailable callback endpoint; never credit twice because the same paid event arrives again.

Related concepts

Invoice Payment Network, Invoice Remaining Amount, Crypto Invoice.