Payment integration looks simple in the quickstart and gets hard the moment real money flows. The demo takes a card and returns success. Production has failed charges, disputes, refunds, currency edge cases, and a webhook that arrives twice. This checklist covers what separates a demo integration from one you can trust with revenue.
Never let the card touch your server
The single most important rule: card data should go straight from the browser to the processor, never through your backend. Use hosted fields or a hosted checkout — Stripe's Payment Element, Checkout, or the equivalent from your provider. This keeps you in the lightest PCI compliance tier and takes an entire class of breaches off the table.
If you're storing raw card numbers, stop and redesign. There is almost never a good reason to.
Treat webhooks as the source of truth
The browser redirect after payment is not confirmation — the user can close the tab. The webhook is what actually tells you a charge succeeded. Build around it:
- Verify the signature on every webhook so no one can forge a "payment succeeded" event.
- Make handlers idempotent — providers retry, so the same event can arrive more than once. Key on the event ID and no-op on duplicates.
- Return a fast 2xx and do slow work asynchronously, or the provider will retry and pile up duplicates.
Fulfilling orders from the redirect instead of the webhook is the most common way integrations lose or double-fulfill orders.
Handle the money edge cases
Real payments are messier than "charge succeeds":
- Failed and retried payments — surface clear errors and let the user try another method.
- Refunds and partial refunds — model them from day one, not as an afterthought.
- Disputes and chargebacks — listen for those webhook events and keep records to respond.
- Currency and amounts — store money as integer minor units (cents), never floats.
Design for the strong-auth flow
Regulations like SCA in Europe require extra authentication on many payments. Modern SDKs handle 3-D Secure for you, but only if you use the payment-intent flow properly. Test that the challenge step works — a payment that silently fails SCA looks like a broken checkout to the customer.
Test with the tools, not real cards
Use the provider's test card numbers to simulate success, decline, insufficient funds, and dispute. Trigger test webhooks with their CLI. Confirm your idempotency actually holds by firing the same event twice. Don't discover these paths in production.
Before you go live
- Signature verification on all webhooks.
- Idempotent handlers, keyed on event ID.
- Refund and dispute flows implemented and tested.
- Money stored as integer minor units.
- Secrets in environment config, never in the client bundle.
At Doktouri we integrate Stripe and regional processors into products where a missed edge case means lost revenue. If payments are on your roadmap, let's talk.
Originally published on the Doktouri Agency blog. We build web, mobile, SaaS, and AI products — let's talk.
Top comments (0)