Invoice Callback

Overview

An invoice callback is a server-to-server notification sent to a configured receiver when an invoice or its payment status changes. It enables asynchronous updates when the payer is no longer present in the browser. Delivery success proves only that a message reached an endpoint, not that the business action completed. Callbacks are commonly retried and may be duplicated, delayed, or delivered out of order. A Invoice Callback handler should acknowledge only after durable receipt when the provider’s retry contract depends on the response.

Receivers should verify the provider’s authentication mechanism, parse defensively, deduplicate atomically, and validate allowed state transitions. They should acknowledge quickly, process durable work asynchronously, and query authoritative invoice status when uncertain. An invoice callback informs a merchant system about events such as payment detected, confirmation progress, completion, expiration, failure, or another lifecycle change. Replay of Invoice Callback should preserve original identifiers and timestamps so historical processing cannot masquerade as a new event.

An audit trail for Invoice Callback should link the contract and client version, principal, request identifier, sanitized payload evidence, response, callbacks, retries, overrides, provider references, and final state. For Invoice Callback, metrics should separate transport success from business success. Payload fields can also become stale after a later invoice update. Logs need correlation identifiers without exposed secrets or sensitive payloads. The Invoice Callback path should preserve ordering and duplicate evidence so delayed delivery cannot silently overwrite a newer state.

Recovery for Invoice Callback should combine replay controls with an authoritative status check rather than trusting delivery history alone.