Payment Gateway Integration: What Developers Need to Get Right
Payment integration looks simple in a tutorial and is unforgiving in production, because every failure case involves either a customer who paid and got nothing or a customer who got something and did not pay.
This guide covers how the flow works, the design decision that prevents most problems, and the cases worth testing deliberately before launch.
How the flow actually works#
Whatever the provider, the shape is the same: your server creates an intent to charge, the customer authenticates with the payment provider, and the provider tells you the outcome — twice, by two different routes.
- Your server creates a payment intent with an amount, currency and a reference to your order.
- The customer enters card details in a hosted field or a hosted page, so the data never touches your server.
- Strong authentication may be required, adding a step the customer must complete.
- The provider redirects the customer back to your site with a result.
- Separately, the provider sends a server-to-server webhook with the authoritative result.
- Your system updates the order — from the webhook, not from the redirect.
- Fulfilment is triggered only after the payment is confirmed.
Steps 4 and 5 are the whole design. The redirect is a hint about what happened; the webhook is the fact.
Why webhooks must be the source of truth#
The customer's browser is an unreliable narrator. It can close during the redirect, lose connection, or be manipulated. If your order status depends on the customer arriving back at your success page, you will have paid orders that were never recorded.
- Update order state only from verified webhooks; treat the redirect purely as a user-facing message.
- Verify webhook signatures. An unauthenticated endpoint that marks orders paid is exactly as bad as it sounds.
- Make webhook handling idempotent — providers retry, and duplicates will arrive.
- Respond quickly and process asynchronously; slow endpoints get retried and eventually disabled.
- Log every webhook payload. Payment disputes are settled with logs.
- Handle events out of order, because they can and will arrive that way.
The failure cases worth testing#
Each of these happens in production. Test them deliberately, with the provider’s test cards, before launch.
| Case | What must happen |
|---|---|
| Customer closes the tab after paying | Webhook still completes the order; confirmation email is sent |
| Card declined | Clear message, basket preserved, another attempt possible |
| Strong authentication failed | Order not confirmed; customer told what to do next |
| Duplicate webhook | Order updated once, not twice; no second dispatch |
| Webhook arrives before the redirect | Success page reflects the already-completed order |
| Partial refund | Order totals and any accounting export stay consistent |
| Stock ran out between payment and fulfilment | Defined process: refund, backorder or substitute |
| Currency rounding | The charged amount matches the displayed total exactly |
Scope, compliance and money#
A few decisions determine how much regulatory burden you take on and how much of the transaction you keep.
- Never store card numbers. Use hosted fields or a hosted page so card data never reaches your server; this keeps PCI scope minimal.
- Understand the fee structure. Percentage plus fixed fee, plus currency conversion, plus chargeback fees. The headline percentage is not the cost.
- Check payout timing. Days to settlement affects cash flow more than a small rate difference.
- Confirm the refund path works end to end before launch, including partial refunds.
- Support the local methods your market actually uses — cards are not the default everywhere, and missing the dominant local method costs conversions.
- Keep a second provider ready if payments are critical. Outages happen and they stop revenue entirely.
Frequently asked questions
Should I use a hosted checkout or an embedded form?
Hosted checkout is simpler, keeps PCI scope smallest, and is maintained by the provider — for most stores it is the right default. Embedded fields keep the customer on your domain and give more control over the experience, at the cost of more code and more responsibility. Both keep card data off your server, which is the part that matters.
What happens if my webhook endpoint is down?
Providers retry with backoff, typically for hours or days, so a short outage recovers by itself. A long outage means orders sitting unconfirmed, so monitor the endpoint and alert on failures. Also build a reconciliation job that compares provider transactions against your orders daily — it catches everything the retries missed.
Do I need to handle strong customer authentication?
If you sell to customers in regions that require it, yes, and modern provider SDKs handle most of the flow. What you must handle is the outcome: an order that is pending authentication is not paid, and treating it as paid means shipping goods you were never paid for.
How do I test payments safely?
Every provider has a test mode with cards that trigger specific outcomes — decline, authentication required, fraud. Run the full list, including the awkward cases in the table above. Then make one small real transaction in production before launch and refund it, because test mode does not exercise your live keys or your live webhook URL.
payment gateway integrationecommerce paymentswebhookspci compliancecheckout developmentonline payments
