Adding payments to a site looks like a solved problem until real money moves. Then the questions start: why did this order charge twice, why is this refund missing, why does the bank statement disagree with the store.
Payment gateway integration is less about connecting to Stripe or PayPal, that part is documented, and more about the decisions around it. This guide covers the choices that matter, in the order they usually bite.
Choose the checkout model first
Every gateway offers two broad paths: a hosted checkout, where the customer pays on the provider page or embedded component, and a direct API integration, where your site runs the payment flow itself.
- Hosted checkout (Stripe Checkout, PayPal buttons) ships fast, keeps card data off your servers, and inherits the provider fraud tooling. The trade is less control over the page.
- Direct API integration gives full control over the payment experience and covers flows the hosted page cannot express: split payments, complex subscriptions, marketplaces.
- Most businesses should start hosted and move specific flows to the API when a real requirement forces it, not before.
Webhooks are the source of truth
The redirect back to your thank-you page is not proof of payment. Customers close tabs, connections drop, and some payment methods confirm minutes later. The webhook, the signed server-to-server notification from the gateway, is the record to trust.
- Mark orders paid from the webhook, never from the browser redirect.
- Verify webhook signatures. Without that check, anyone can forge a paid order.
- Handle retries. Gateways resend webhooks, so processing must be idempotent or you will ship one order twice.
- Log every event with its payload. When finance asks about a charge in three months, the log answers.
Failure paths are the real work
The happy path takes a small share of the build time. The rest goes to the cases that hit real stores every week:
- Declines and retries. The customer tries again; the integration must not double-charge or strand a half-created order.
- Refunds and partial refunds. They have to flow back into the store and the accounting system, not just the gateway dashboard.
- Disputes and chargebacks. You need the order evidence organized before the deadline, not scattered across systems.
- Currency and rounding. Multi-currency stores reconcile to the cent or finance stops trusting the numbers.
PCI scope, in one honest paragraph
If you use a hosted checkout or hosted card fields, card data never touches your servers and your PCI burden stays at the short questionnaire level. If you collect card numbers directly, you take on real compliance obligations with audits to match. For most stores there is no business case for touching raw card data. Keep it with the gateway.
Testing that predicts production
Gateways ship test modes with cards that simulate declines, 3D Secure challenges, and disputes. Use them before launch: pay, refund, partially refund, dispute, and force a webhook failure while the site is down, then confirm the order state recovers. An hour of hostile testing before launch saves a week of reconciliation after.
We integrate Stripe, PayPal, and regional gateways into stores and custom platforms, including the webhook and reconciliation work. Get a Custom Quote and tell us what you sell and where.