Invoice Status Callback

Overview

Invoice status callback is the authenticated webhook message sent to a merchant when the state of an invoice or associated payment changes. In an operational payment system, this field or policy should have one authoritative meaning across the API, checkout, webhook, ledger, and support tools.

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. In practice, the system should preserve the original request, the observed blockchain or checkout evidence, and every status change that affects this value. This makes support investigations and financial reconciliation possible without reconstructing the payment from screenshots or mutable client data.

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 implementation should use exact asset precision, authenticated server-side updates, and idempotent processing wherever repeated API calls, blockchain observations, or webhook deliveries can occur.

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. It should be interpreted alongside Invoice Callback URL, Invoice Success URL, Invoice Fulfillment Rule. These concepts belong to the same workflow, but each answers a different operational question and should not be collapsed into one ambiguous field.

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. The practical test is whether a merchant can explain how the value was produced, verify it independently, and apply the same rule consistently when the payment is delayed, duplicated, partially paid, refunded, or reviewed manually.