Payment Gateway Integration Guide for India: Architecture and Security

Integrating a payment gateway into a SaaS product or e-commerce platform is a narrower, more standardized problem than corporate bank API integration for bulk payments — but it's still where a lot of avoidable production incidents come from: double-charged customers, orders marked paid that never actually settled, and refunds that don't reconcile. The gateway providers (Razorpay, PayU, Cashfree, Stripe and similar) have largely converged on a similar integration shape, which makes the patterns in this guide broadly applicable regardless of which specific provider you choose.

This guide covers checkout flow architecture, webhook handling, idempotency, refunds, reconciliation, and where PCI DSS compliance scope actually falls for a typical integration — distinct from the bulk B2B payment orchestration covered in our [corporate bank API integration guide](/blog/corporate-bank-api-integration), which addresses a different problem (payroll and vendor disbursal, not customer checkout).

Checkout flow architecture

The standard pattern most Indian payment gateways converge on: your backend creates an "order" or "payment intent" via the gateway's API, the frontend uses the gateway's hosted checkout (a widget or redirect) to collect payment details, and the gateway handles the actual card/UPI/wallet processing — your application never touches raw card numbers. After payment, the gateway returns the customer to your application, and separately notifies your backend via webhook.

That last point is the detail most integration bugs come from: the redirect back to your application is not proof of payment. A user can close the browser tab before the redirect completes, or the redirect can fail, while the payment itself succeeded. The webhook — a server-to-server notification — is the actual source of truth, and your backend should treat the client-side redirect as, at most, a hint to show the user a status page while the real status comes from the webhook and a server-side verification call.

Webhook handling

Customer completes checkout

Via the gateway's hosted widget — your app never sees raw card data

Gateway processes payment

Settlement happens on the gateway/bank side, asynchronously

Webhook sent to your backend

Server-to-server notification of the payment outcome

Signature verification

Confirm the webhook genuinely came from the gateway before trusting it

Server-side status verification

Call the gateway's status API to independently confirm, don't trust the webhook payload alone for high-value actions

Order/subscription updated

Your application's records are updated based on verified status

Customer notified

Confirmation shown or sent, independent of whether the redirect completed

Every gateway signs its webhook payloads — verify that signature before trusting the payload, exactly as you would for any external callback. An unverified webhook endpoint is a real attack surface: anything that can guess your endpoint URL could otherwise submit fake "payment successful" notifications.

Idempotency and duplicate handling

Webhooks are typically delivered "at least once," meaning your endpoint can receive the same notification multiple times. Process webhooks idempotently — using the gateway's payment/order ID to detect and safely ignore a duplicate delivery — the same discipline covered in our corporate bank API integration guide for bulk payments, applied here to customer-facing checkout instead.

Similarly, if your frontend allows a retry on a failed or slow checkout attempt, generate a unique idempotency key per checkout attempt and pass it to the gateway, so a network retry doesn't create a duplicate charge for the same purchase.

Refunds

Refunds are asynchronous, just like the original payment — initiating a refund via the API doesn't mean money has moved yet. Track refund status the same way you track payment status (via webhook and status verification), and reflect that intermediate "refund processing" state to the customer rather than assuming instant completion. For subscription products specifically, refund logic needs to interact correctly with your billing and entitlement system — see our SaaS development cost guide for how subscription billing and plan management are typically scoped.

Reconciliation

On a schedule (daily is typical), reconcile your application's payment records against the gateway's own settlement report — the same principle covered in our corporate bank API integration guide: the gateway's report is the actual source of truth, and a reconciliation job catches anything a missed or delayed webhook didn't.

Where PCI DSS scope actually falls

PCI DSS (Payment Card Industry Data Security Standard) compliance requirements scale with how much of the raw cardholder data flow your systems actually touch. The practical takeaway for most SaaS and e-commerce integrations: using the gateway's hosted checkout widget or redirect (rather than building your own card-entry form) keeps raw card data off your servers entirely, which dramatically reduces your PCI scope compared to handling card numbers directly. Most businesses integrating a mainstream Indian payment gateway should default to this approach unless there's a specific, well-justified reason to handle card data directly — which brings a materially higher compliance burden most businesses don't need to take on.

Security checklist beyond PCI scope

• Webhook signature verification on every incoming webhook, not just during initial integration testing.
• HTTPS/TLS for all communication with the gateway, without exception.
• API keys in a secrets manager, never in client-side code or version control.
• Server-side amount verification — never trust a payment amount passed from the client; verify it against your own order record before confirming a purchase.
• Rate limiting on payment-initiation endpoints to limit abuse.
• Audit logging of every payment state change, for both security and dispute-resolution purposes.

Implementation checklist