Payment API and webhooks: how to integrate payments reliably

How do payment APIs and webhooks work together?

Your server calls the API to create a payment and gets an ID and a status such as pending or requires action. The final result often arrives later: after a 3DS challenge, a bank redirect or a voucher payment. The provider then sends a webhook, an HTTP POST to your endpoint, with the event.

How do you make payment requests safe to retry?

Network timeouts happen. Send an idempotency key, a unique value per intended operation, with each create or refund request; if you retry with the same key, the provider returns the original result instead of charging twice. The IETF is standardising this as the Idempotency-Key header.

How should you handle webhooks?

Build the endpoint for duplicates, delays and order changes.

1. Verify Check the signature and timestamp with your webhook secret, as in the Standard Webhooks specification.
2. Acknowledge fast Return a 2xx status quickly and process the event in a queue.
3. Deduplicate Store event IDs and ignore events you have already processed.
4. Reconcile state Fetch the payment from the API if events arrive out of order.
5. Retry safely Expect the provider to resend events that were not acknowledged.

How does OrsunPay simplify payment APIs and webhooks?

OrsunPay is a payment orchestration platform: you keep your own contracts with licensed providers (for example Stripe, Adyen or Worldpay), and OrsunPay is not a payment institution, acquirer or merchant of record and does not hold or transmit funds. OrsunPay gives you one API and one signed webhook format across connected providers, with idempotent requests and one set of payment states. For OrsunPay pricing, see the pricing page at /pricing.