Ecommerce Payment Gateway Integration: A Practical Guide
How to integrate payment gateways into an ecommerce store: choosing providers, local methods, authorization and capture, webhooks, refunds, fraud and reconciliation.
Quick answer
Ecommerce payment gateway integration connects checkout, orders and finance. Choose providers by market coverage, methods, platform fit, fees and tooling; offer the cards, wallets and local methods your customers use; decide between immediate capture and authorize-then-capture on fulfilment; process webhooks with signature verification, deduplication and idempotency; run refunds from the order system; use provider fraud tools; keep card data off your servers with hosted checkout or fields; and reconcile payouts, fees and refunds with orders in your ERP.
Payments in the Order Lifecycle
In ecommerce, a payment isn't a single event. It's authorized at checkout, captured at checkout or fulfilment, partially refunded on returns, sometimes disputed and eventually paid out in a batch with fees deducted. The flow above traces that lifecycle. For the general mechanics of payment flows on any website, see payment gateway integration.
Choosing Providers
When one provider is not enough, see payment orchestration and payment routing.
| Criterion | Questions |
|---|---|
| Markets and currencies | Can you accept and settle in each market? |
| Methods | Cards, wallets, bank transfers, buy now pay later, local methods? |
| Platform fit | Native integration with your platform and checkout? |
| Fees and payouts | Transaction fees, FX, payout timing? |
| Risk tools | Fraud screening, 3-D Secure, dispute management? |
| Subscriptions | Stored credentials, retries, network updates? |
| Reporting | Payout and fee data for reconciliation? |
Authorization and Capture
Immediate capture is simple and suits most digital and in-stock orders. Authorize-then-capture suits made-to-order goods, variable weights (such as groceries) and pre-orders. Authorizations expire after provider-defined periods, so plan capture timing and re-authorization. Split shipments may need multiple captures where supported.
Webhooks and Asynchronous Outcomes
Redirect-based and delayed payment methods, disputes and refunds are reported asynchronously. Stripe's documentation, for example, notes that webhook events can be retried for up to three days in live mode, may arrive out of order and may be duplicated, so handlers should verify signatures against the raw request body, deduplicate by event ID, return a 2xx quickly and process asynchronously. Other providers have similar guidance.
on payment webhook(request):
event = verifySignature(request.rawBody, request.signatureHeader)
if processed(event.id): return 200
enqueue(event)
return 200
worker:
order = findOrderByPaymentRef(event.paymentId)
apply transition (authorized → captured → refunded / disputed)
ignore transitions that move backwards
markProcessed(event.id)Payments not matching orders?
ZSpace Labs integrates payment providers with ecommerce orders and finance so every payment reconciles.
Payment Methods by Market
Customers expect familiar methods. Offer the major wallets for express checkout and local methods where they're common. Show methods early (on product and cart pages) where it helps confidence. Test each method end to end, including refunds. See checkout UX.
Refunds and Disputes
Refunds should start from the order or returns system, not directly in the gateway dashboard, so order, inventory and finance stay consistent. Disputes need evidence (order details, tracking, communications) gathered quickly. Sync refunds and dispute outcomes to the ERP and CRM.
Automated refund workflows are covered in refund automation and dispute handling in chargeback management.
Security and Card Data
Use hosted checkouts, hosted payment fields or platform-native checkout so card data never touches your servers. This reduces PCI scope significantly. Protect API keys, restrict dashboard access and never log payment details. See website security checklist.
Reconciliation
- Match payouts to orders, refunds and fees
- Record FX and fees in accounting
- Track disputes and chargebacks
- Reconcile daily, with alerts for mismatches
- Keep gateway references on ERP orders
Worked Example: Authorize at Checkout, Capture on Shipment
An illustrative scenario: a furniture retailer sells made-to-order items that ship in several weeks. Cards are authorized at checkout, but authorizations expire long before shipment, so the retailer takes a deposit at checkout and charges the balance before dispatch using a stored payment method with the customer's consent. Where items ship separately, each shipment triggers a capture or charge for its value. Every payment event updates the order in the store and ERP, and refunds for cancelled items reverse the right charge.
Payment Data in the Order and Finance Flow
| Event | Store | ERP / accounting |
|---|---|---|
| Authorization | Order marked authorized | No revenue yet |
| Capture | Order marked paid | Receipt recorded |
| Refund | Refund recorded on order | Credit note / refund |
| Dispute | Order flagged | Provision or chargeback |
| Payout | — | Bank deposit matched to payments and fees |
Common Payment Integration Mistakes
- Trusting the browser redirect instead of the webhook
- Processing the same event twice
- Refunds issued in the gateway dashboard only
- Letting authorizations expire before capture
- No reconciliation of payouts to orders
- Card data passing through your servers unnecessarily
Shopify Considerations
Shopify's checkout supports Shopify Payments and third-party payment providers, with wallets and local methods depending on region. Card handling is managed by the platform, so integration work focuses on provider selection, payment method configuration by market and connecting payout, fee and refund data to finance systems. See Shopify checkout optimization.
Testing
- Successful, declined and authentication-required payments
- Delayed and redirect-based methods
- Partial and full refunds
- Duplicate and out-of-order webhooks
- Authorization expiry and re-authorization
- Payout reconciliation with test data
Ready to integrate payments properly?
Talk to ZSpace Labs about payment integration, Shopify payments setup and checkout conversion.
Conclusion
Payment integration in ecommerce is about the whole lifecycle: authorization, capture, refunds, disputes and payouts, reliably reflected in orders and finance. Choose providers for your markets, handle events robustly and reconcile every day. For the checkout experience, see why customers abandon checkout.
For related guides, see marketplace payment architecture and international payments.
Common questions.
Connecting a store's checkout with payment providers so customers can pay using cards, wallets and local methods, and so the store receives payment status, refunds and payouts reliably.
Consider supported markets and methods, platform compatibility, fees, payout timing, fraud tools, subscription support, dispute handling and reporting.
Authorization checks and holds funds; capture takes them. Stores that ship later, or charge variable amounts, may authorize at checkout and capture on fulfilment, within the provider's time limits.
Many payment outcomes happen asynchronously (bank redirects, delayed methods, disputes). Webhooks tell the store about them. Handle them with signature verification, deduplication and idempotent processing.
Those your customers use: cards, major wallets and local methods for each market. Check checkout data and market norms.
From the order system through the gateway, with partial refunds for returns, and accurate sync back to the ERP and CRM.
Every business accepting cards has obligations. Using hosted checkouts or provider-hosted fields keeps card data off your servers and greatly reduces scope. Confirm requirements with your provider.
Shopify checkout supports Shopify Payments and third-party providers; custom card handling isn't built into the store. Most integration work on Shopify is choosing providers and connecting payout and order data to finance.
Offer relevant methods, support authentication flows smoothly, show clear decline messages, and monitor failure rates by method, issuer and market.
The general guide covers payment flows for any website. This guide covers ecommerce-specific concerns: order lifecycle, capture on fulfilment, refunds, multi-market methods and reconciliation.