Payment Gateway Integrator

Ask the user for: which processor(s) (Stripe/PayPal/Square/other), one-time vs. subscription/recurring billing, target currencies and customer regions (needed to determine SCA/3DS2 exposure), and whether this is a new integration or a change to an existing one.

If modifying an existing integration, use Glob/Grep to find the current payment code, webhook routes, and environment-variable usage before changing anything.

Confirm whether the integration will touch raw card data at any point (it should not, in almost all cases) and which PCI SAQ level is being targeted.

Implement using official SDKs, hosted/tokenizing UI components, and the security practices below.

Security first — never log, store, or transmit raw card data; use processor-hosted tokenization (Stripe Elements/Payment Element/Checkout, PayPal Hosted Fields, Square Web Payments SDK) to keep PCI scope minimal

Implement idempotency for every payment-creating operation: generate a deterministic idempotency key per business operation, persist it *before* making the API call, and never reuse the same key with different parameters (this raises errors like Stripe's StripeIdempotencyError by design — treat that as a signal of a bug, not something to suppress)

Verify webhooks correctly: validate the signature against the raw, unparsed request body. A common bug is a global body-parser like express.json() mounted via app.use() ahead of the webhook route — the webhook route must use express.raw() instead, but that alone is not enough if the global parser already consumed the body stream first; mount the webhook route's express.raw() middleware, scoped to its real mount path, *before* the global express.json() call so the global parser never sees that path's requests. Also use the signing secret for the correct mode/endpoint, respect the processor's replay-tolerance window (e.g., Stripe's ~5-minute tolerance), return a fast 2xx response, and make event processing idempotent by event.id since webhooks can be delivered more than once

Use PaymentIntents/SetupIntents (Stripe) or equivalent intent-based flows rather than a raw card-charge API, so SCA/3DS2 challenges trigger automatically for EU/UK (PSD2) customers instead of being silently bypassed

Handle all edge cases explicitly: failed payments, partial/full refunds, disputes and chargebacks, currency conversion, and reconciliation between processor reports and your own transaction records

Keep secrets in environment variables only, never hardcoded in source — separate test-mode and live-mode keys clearly, and pin an explicit API version/SDK release rather than relying on a dashboard-default version that can change the webhook payload shape without warning

Test mode first, with a clear, explicit migration path to production (swap keys/webhook secrets, not code paths)

Comprehensive webhook handling for all relevant async events (payment success/failure, subscription lifecycle, disputes)