Payment Callback URL

Overview

A payment callback URL is the merchant-controlled HTTPS endpoint where a payment provider sends asynchronous transaction status notifications. Payment Callback URL is the configured destination for payment notifications, not the notification payload, authentication method, or proof that processing succeeded. Use a stable HTTPS origin, strict routing, provider authentication, body-size limits, and fast durable acknowledgment. Because the endpoint is public, attackers can probe it, replay old messages, or send forged payloads. Monitor delivery health and maintain a replay and reconciliation process. If users can influence destinations, apply allowlists and SSRF defenses. The Payment Callback URL path should preserve ordering and duplicate evidence so delayed delivery cannot silently overwrite a newer state.

Data modeling for Payment Callback URL should use stable identifiers, explicit timestamps and timezones, documented decimal and currency rules, nullable-field semantics, enumerated statuses, and immutable historical references. The URL is configured globally or supplied when creating a payment request, depending on the provider. It must be reachable from the provider and route events to a handler that understands the expected authentication and payload format. Redirects, dynamic user-supplied hosts, DNS changes, certificate failures, and private-network destinations can create security or delivery problems. For Payment Callback URL, the event identifier, signature result, delivery attempt, and resulting business state should remain connected throughout processing.

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

A Payment Callback URL handler should acknowledge only after durable receipt when the provider’s retry contract depends on the response.