Merchant Callback

Overview

A merchant callback is a server-to-server message sent by a payment provider to a merchant endpoint when a transaction or payment state changes. A successful HTTP response confirms delivery, not correct business processing. The endpoint should acknowledge quickly and queue durable work. They let the merchant update orders even when the customer closes the browser. A Merchant Callback handler should acknowledge only after durable receipt when the provider’s retry contract depends on the response.

The merchant should use HTTPS, verify authenticity, validate the schema, deduplicate atomically, and enforce legal state transitions. Merchant callbacks deliver asynchronous information such as payment detection, confirmation progress, completion, failure, expiration, refund, or another provider-defined event. When status is uncertain, the integration should query the provider and reconcile identifiers, amounts, currencies, and final outcomes. Payload data can also be stale or forged if the receiver does not verify the documented authentication mechanism. Business actions triggered by Merchant Callback should be idempotent and should verify the current object state before fulfillment or accounting updates.

An audit trail for Merchant Callback should link the contract and client version, principal, request identifier, sanitized payload evidence, response, callbacks, retries, overrides, provider references, and final state. Merchant Callback participates in event creation, signing, delivery, receipt, durable storage, processing, retry, and reconciliation. Callbacks cross an untrusted network and may be delayed, repeated, or reordered. Monitoring for Merchant Callback should track delivery age, signature failures, duplicate rate, retry exhaustion, and unresolved business events.

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