Payment gateway integration: options, steps and go-live checklist

What is payment gateway integration?

A payment integration covers more than taking a card: it includes creating payments, handling 3-D Secure, receiving status updates through webhooks, issuing refunds and reconciling payouts. A gateway passes payment data to processors and acquirers; see payment gateway vs processor.

Integration options compared

The PCI Security Standards Council defines which self-assessment questionnaire applies to each pattern (PCI SSC). A hosted payment page is the usual low-scope route.

Payment gateway API integration step by step

Treat sandbox behaviour as binding before you switch to live keys.

1. Get sandbox credentials Get sandbox credentials and read the API reference.
2. Create a payment Create a payment server-side with amount, currency, order ID and return URLs.
3. Collect payment details Collect payment details via hosted page, embedded fields or SDK.
4. Handle authentication Support the 3-D Secure redirect or challenge flow (see 3D Secure 2).
5. Receive webhooks Receive webhooks and update the order only from verified webhook events.
6. Support refunds Support refunds and partial refunds.
7. Reconcile Reconcile: match settlements and fees to orders.
8. Test and go live Test edge cases, then switch to live keys.

Webhooks and idempotency

Webhook handling is where many production bugs hide.

• Verify the webhook signature before trusting the payload.
• Treat webhooks as "at least once": the same event can arrive twice.
• Use idempotency keys when creating payments or refunds so a network retry does not charge twice.
• Return a 2xx response quickly and process heavy work asynchronously.

Integrating several providers at once

Adding a second provider often means a second integration with different objects, statuses and webhooks. An orchestration layer normalises this: one API and one webhook format while traffic goes to several providers. It also makes payment routing and failover possible without rebuilding checkout.

Testing before go-live

Run test cards for success, decline, 3DS challenge and timeouts; replay webhooks; test refunds and currency rounding. Our payment gateway testing guide lists the cases.

Go-live checklist

Treat this as a minimum before you move real money.

• Live keys stored in a secrets manager.
• Webhook endpoint public, signed and monitored.
• Error messages shown to the customer are clear.
• Refund and support process documented.
• Alerts on approval-rate drops.

How OrsunPay helps with payment integration

OrsunPay is a payment orchestration platform that connects you to licensed PSPs; it does not process or hold funds itself. One API and a hosted checkout connect to the providers you choose. Developer docs are at docs.orsunpay.com, and the team helps with setup through integration support. Plans are on the pricing page.