Why AI-Built Apps Break at Payments and Authentication, and How to Integrate Subscriptions Safely

How do you integrate subscriptions, payment gateways and webhooks safely?

Let the payment provider hold card data and act as the source of truth, use its hosted checkout and customer portal where you can, and drive access from verified webhooks. Verify every webhook signature against the raw body, return a 2xx quickly and process the event in a background job, skip events you have already processed, and fetch current subscription state rather than trusting event order. Then test renewals, failed payments, upgrades and cancellations with simulated time before launch.

Step 1: Choose the integration that keeps card data off your servers

Use the provider's hosted checkout or embedded payment elements, so card numbers go straight to the provider. Stripe's integration security guide says that handling card data directly might require meeting more than 300 PCI DSS security controls, while its low-risk integrations send payment details directly to Stripe and reduce your obligations. Decide early whether you want a payment processor such as Stripe, where you handle sales tax and invoicing obligations yourself, or a merchant of record, which takes on more of that for a higher fee; our SaaS tech stack guide compares the two.

Step 2: Model subscription state in your own database

Store a small, explicit record per customer or organisation: the provider's customer ID, subscription ID, plan, status (for example trialing, active, past due, cancelled) and the end of the current period. Your app grants features from this record, which we call entitlements, never from a flag set by the browser. Keep the mapping from plan to features in one place in your code, so a pricing change is a one-line edit rather than a search through the codebase.

Step 3: Build a webhook handler that survives the real world

1. Verify the signature on the raw request body. Stripe signs each event in the Stripe-Signature header and requires the unmodified raw body for verification; frameworks that parse JSON first break this. Keep the library's default timestamp tolerance (five minutes in Stripe's libraries) to block replayed events, and never set it to zero.
2. Return a 2xx quickly, then do the work in a background job or queue. Stripe says to return a successful status before any complex logic that could time out, and recommends asynchronous processing so renewal spikes do not overwhelm your servers.
3. De-duplicate. Store each processed event ID and skip repeats. Make the fulfilment logic itself safe to run twice: Stripe notes that its fulfilment function might be called multiple times, possibly concurrently, for the same checkout session.
4. Do not depend on order. Stripe advises against using an event's timestamp to decide order. When an event arrives, fetch the current subscription from the API and write that state, rather than applying events as a sequence of changes.
5. Listen only to the events you need, typically checkout completion, invoice paid, invoice payment failed, and subscription updated and deleted.
6. Rotate the signing secret periodically and whenever it may have been exposed; Stripe lets you keep the old secret active for up to 24 hours while you switch.

Step 4: Make outgoing payment calls idempotent

When your server creates or updates something at the payment provider, a network timeout leaves you unsure whether it happened. Send an idempotency key with every create or update request. Stripe's API documentation explains that a retried request with the same key does not perform the operation twice; it suggests random V4 UUIDs, warns against using personal data such as email addresses as keys, and notes that for its v1 API, saved keys can be pruned after 24 hours.

Step 5: Let the provider's portal handle self-service

Card updates, invoice history, plan changes and cancellation are standard screens. Stripe's customer portal provides them, so your engineering effort goes into reacting to the resulting webhooks correctly. What you do when a renewal fails, how long you allow before restricting access and what emails you send, is covered in our guide to failed payments and dunning.

Step 6: Secure the authentication around billing

• Use a managed authentication provider or a well-maintained framework library rather than building login yourself. See what not to build in a SaaS.
• Follow OWASP's session guidance: renew the session ID after login or any privilege change, set Secure, HttpOnly and SameSite on session cookies, and invalidate sessions on the server at logout.
• Restrict who can change billing. In a B2B product, only an organisation's owner or billing admin should be able to change plan or payment method, and that check belongs on the server.
• Log billing and permission changes (who, what, when) without logging card details or secrets.

Step 7: Test the lifecycle before launch, not after

Stripe's test clocks (its billing simulations) exist for exactly this: they advance time so you can see how subscriptions, trials and renewal failures behave and confirm that your integration processes the billing lifecycle webhooks correctly. Add a nightly reconciliation job that compares your stored subscription states with the provider's, so a missed event is caught within a day rather than discovered by a customer. Our SaaS launch checklist covers the rest of what to check before going live.