Why Payment Gateway Integration Fails (and How to Get It Right the First Time)

Cover design: Vishvajeet Shukla

We've wired Razorpay into several production products now — a personal-legacy SaaS, a floral subscription platform with recurring billing, and internal tooling. The integration bugs that actually cause production incidents are almost never in the "customer pays, everything succeeds" path. They're in the parts most teams don't think to test.

The webhook arrives more than once — plan for it

Payment gateways retry webhook delivery on any non-2xx response, network blip, or timeout on your end. If your webhook handler isn't idempotent — if processing the same event twice can double-credit an order or send a duplicate confirmation — you will eventually see it happen in production, usually during a traffic spike when your server is slowest to respond and retries pile up. Every webhook handler needs to check "have I already processed this event ID" before doing anything else.

The client-side "success" and the server-side "success" are different events

A payment succeeding in the browser (the checkout modal closing, the redirect firing) is not the same as your server confirming it via the gateway's webhook or a verified callback. Treating the client-side success as authoritative is how orders get marked "paid" when the payment actually failed server-side verification, or never fully settled. The webhook — verified with the gateway's signature — is the only source of truth.

Partial and delayed states need real handling, not just "pending"

Real payment flows include states beyond success/failure: authorized-but-not-captured, refund-in-progress, disputed. A subscription platform with recurring billing (like our own PetalLoop-style wallet checkout work) has to handle a renewal payment failing on day 30 differently than an initial payment failing on day 1 — the business logic for "what happens next" is different for each, and treating them all as one generic "pending" state is where recurring-billing bugs live.

Signature verification isn't optional, even in staging

Every webhook payload needs signature verification against the gateway's shared secret before you trust a single field in it. Skipping this "just for staging, we'll add it before launch" is exactly how it stays skipped — because staging works fine without it, right up until it doesn't in production.

Reconciliation is a feature, not an afterthought

Every payment-integrated product needs a way to answer "does our database agree with the gateway's records" without manually cross-referencing a dashboard. A scheduled reconciliation job that flags mismatches is what turns a silent data-drift bug into a same-day alert instead of a support ticket three weeks later.

The happy path in a payment integration is the easy 20%. The webhook retries, the partial states, and the reconciliation job are the 80% that actually determines whether the integration holds up in production.

If you're scoping a payment integration and the plan only covers the checkout flow, ask specifically about webhook idempotency and reconciliation before writing any code — they're cheap to design in from day one and expensive to retrofit after a real incident.