Invoice Callback URL

Overview

What it means and why it matters

An invoice callback URL is the merchant-controlled HTTPS endpoint that receives asynchronous payment notifications for a particular invoice or integration. It allows the merchant to react without repeatedly polling an API.

How it works in practice

When creating an invoice, the merchant configures an allowed callback destination. The provider sends events such as pending or paid to that endpoint. The merchant verifies authenticity, matches the event to its own invoice, records it durably and updates order state according to permitted transitions.

Technical detail without the jargon

Protect endpoints against server-side request forgery by restricting where a provider may send callbacks where supported. On the merchant side, use HTTPS, verify the provider’s signatures or authentication method, rotate shared secrets carefully and handle duplicate events.

A deeper point to understand

A callback endpoint must not assume that a return from the customer’s browser is equivalent to server-to-server evidence. The customer can close the browser and payment can still succeed. Separate the callback workflow from frontend redirects, and base final order status on verified payment data.

Common mistakes and limitations

A callback URL is a destination, not an authentication token. An attacker who learns it may send fake requests unless the merchant verifies authenticity. Return an appropriate success response only after durable handoff.

What to check in a real payment system

Use an HTTPS destination owned by the merchant and confirm that its handler validates provider-origin evidence. Apply tenant and invoice binding checks before fulfillment. If callers can configure arbitrary callback URLs, protect the provider from SSRF against private and metadata addresses.

Related concepts

Webhook, Webhook Verification, API Key.

Further reading

OWASP — Webhook Security.