Invoice Callback URL

Overview

An invoice callback URL is the HTTPS endpoint supplied by a merchant so a payment provider can send machine-readable notifications when an invoice or its associated payment changes state. Its practical value comes from making the payment lifecycle deterministic for the payer, merchant, support team, and accounting system.

The provider typically sends an authenticated HTTP request containing identifiers, amount data, asset and network information, and a status such as paying, paid, failed, or expired. Delivery may be retried because networks and merchant servers can fail temporarily. 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.

The endpoint should validate the callback signature, use HTTPS, return the required success response, process events idempotently, reject stale or malformed payloads, and store enough data for replay and audit. Fulfillment must not rely solely on an unauthenticated browser redirect. 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.

A callback URL is server-to-server and event-driven. It is different from an invoice return URL or success URL, which sends the payer’s browser back to a merchant-controlled page and does not independently prove payment. It should be interpreted alongside Invoice Status Callback, Invoice Return URL, Invoice Success URL. These concepts belong to the same workflow, but each answers a different operational question and should not be collapsed into one ambiguous field.

For example, after an invoice becomes paid, the provider posts the invoice ID, order ID, amount, currency, and status to the callback URL; the merchant verifies the event and updates the order exactly once. 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.