Merchant Callback
Pronunciation: MUR-chunt KAWL-bak
Definition
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. Merchant Callback must specify the producer, consumer, event type and version, delivery URL, stable event identifier, signature method, timestamp, retry policy, and expected response.
Overview
Meaning and scope
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. Merchant Callback must specify the producer, consumer, event type and version, delivery URL, stable event identifier, signature method, timestamp, retry policy, and expected response.
Mechanism and operation
The endpoint should acknowledge quickly and queue durable work. They let the merchant update orders even when the customer closes the browser. 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.
Practical payment example
A checkout backend authenticates a provider callback, matches its order identifier and checks the final payment state before updating the commerce platform.
Operational checks
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.
Distinctions and limits
A successful HTTP response confirms delivery, not correct business processing. A Merchant Callback handler should acknowledge only after durable receipt when the provider’s retry contract depends on the response. 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.
Related reading
Related definitions: payment detection, authentication.
Example
A checkout backend authenticates a provider callback, matches its order identifier and checks the final payment state before updating the commerce platform.
Comparison
A Merchant Callback handler should acknowledge only after durable receipt when the provider's retry contract depends on the response. Payload data can also be stale or forged if the receiver does not verify the documented authentication mechanism.
Key Takeaway
Merchant callbacks must be authenticated, idempotent, state-aware, and reconciled before they trigger irreversible business actions.
Sources
- IETF RFC 9110 — IETF (2026-07-30)
- OpenAPI Initiative Documentation: V3.2.0 — OpenAPI Initiative (2026-07-30)
- OxaPay Documentation: Webhook — OxaPay (2026-07-30)