Stripe Integration
Overview
Stripe provides a complete payments platform with server-side SDKs (Node.js) and client-side libraries (Stripe.js, React Stripe.js). The Node.js SDK handles server operations like creating Payment Intents, managing Subscriptions, and verifying webhooks. The React Stripe.js library provides pre-built UI components (PaymentElement, Elements provider) for secure client-side payment collection.
When to use: One-time payments, recurring subscriptions, usage-based billing, marketplace payouts, hosted checkout pages, custom payment forms, webhook-driven fulfillment.
When NOT to use: Cryptocurrency payments (not supported), regions where Stripe is unavailable, simple static product sales without payment processing (use a hosted storefront).
Quick Reference
| Pattern |
API |
Key Points |
| Hosted checkout |
stripe.checkout.sessions.create() |
Stripe-hosted page, supports payment, subscription, setup modes |
| Payment Intent |
stripe.paymentIntents.create() |
Server-side, returns client_secret for client confirmation |
| Confirm payment |
stripe.confirmPayment({ elements, clientSecret }) |
Client-side, requires Elements instance |
| Create subscription |
stripe.subscriptions.create() |
Use payment_behavior: 'default_incomplete' for SCA |
| Update subscription |
stripe.subscriptions.update() |
Set proration_behavior explicitly |
| Cancel subscription |
stripe.subscriptions.cancel() |
Use prorate: true to credit unused time |
| Customer Portal |
stripe.billingPortal.sessions.create() |
Self-service billing management, returns short-lived URL |
| Webhook verify |
stripe.webhooks.constructEvent() |
Requires raw body, signature header, and endpoint secret |
| Elements provider |
<Elements stripe={stripePromise} options={options}> |
Wraps payment components, pass clientSecret or mode |
| PaymentElement |
<PaymentElement /> |
Renders all supported payment methods automatically |
| Retrieve + expand |
stripe.checkout.sessions.retrieve(id, { expand }) |
Expand nested objects to reduce API calls |
| Search |
stripe.paymentIntents.search({ query }) |
Stripe Query Language for filtering |
Common Mistakes
| Mistake |
Correct Pattern |
| Parsing webhook body as JSON before verification |
Use express.raw({ type: 'application/json' }) to pass raw body to constructEvent |
| Hardcoding payment method types |
Use automatic_payment_methods or let Checkout choose based on currency and region |
| Creating PaymentIntent client-side |
Create on server, pass only client_secret to client |
Not awaiting elements.submit() before confirm |
Call elements.submit() first to trigger validation, then confirmPayment |
Missing return_url in confirmPayment |
Always provide return_url for redirect-based payment methods |
| Using test keys in production |
Store keys in environment variables, validate STRIPE_SECRET_KEY prefix (sk_live_ vs sk_test_) |
Not handling requires_action status |
Check PaymentIntent status after confirmation, handle 3D Secure or other authentication |
| Creating Customer Portal session without settings |
Save portal settings in Dashboard first, otherwise API returns an error |
| Not expanding related objects |
Use expand parameter to include nested objects like latest_invoice.payment_intent |
| Ignoring webhook idempotency |
Use event.id to deduplicate, webhook events can be delivered more than once |
Delegation
- Payment flow architecture: Use
Explore agent to discover integration patterns
- Webhook debugging: Use
Task agent for end-to-end event tracing
- Code review: Delegate to
code-reviewer agent for security review of payment handlers
References
- Checkout Sessions, Payment Intents, and one-time payments
- Subscription lifecycle, pricing models, trials, and Customer Portal
- Webhook endpoints, signature verification, and event handling
- React Stripe.js, Elements provider, PaymentElement, and custom forms
1---2name: stripe-integration3description: Stripe payment integration with Node.js SDK. Covers Checkout Sessions, Payment Intents, Subscriptions, Customer Portal, webhooks, and Stripe Elements. Use when implementing checkout flows, payment processing, subscription billing, webhook handlers, or payment forms with Stripe Elements. Use for stripe, payments, checkout, subscriptions, billing, webhooks, payment intents, stripe elements.4license: MIT5---6
7# Stripe Integration
8
9## Overview
10
11Stripe provides a complete payments platform with server-side SDKs (Node.js) and client-side libraries (Stripe.js, React Stripe.js). The Node.js SDK handles server operations like creating Payment Intents, managing Subscriptions, and verifying webhooks. The React Stripe.js library provides pre-built UI components (PaymentElement, Elements provider) for secure client-side payment collection.
12
13**When to use:** One-time payments, recurring subscriptions, usage-based billing, marketplace payouts, hosted checkout pages, custom payment forms, webhook-driven fulfillment.
14
15**When NOT to use:** Cryptocurrency payments (not supported), regions where Stripe is unavailable, simple static product sales without payment processing (use a hosted storefront).
16
17## Quick Reference
18
19| Pattern | API | Key Points |
20| ------------------- | ----------------------------------------------------- | --------------------------------------------------------------------- |
21| Hosted checkout | `stripe.checkout.sessions.create()` | Stripe-hosted page, supports `payment`, `subscription`, `setup` modes |
22| Payment Intent | `stripe.paymentIntents.create()` | Server-side, returns `client_secret` for client confirmation |
23| Confirm payment | `stripe.confirmPayment({ elements, clientSecret })` | Client-side, requires Elements instance |
24| Create subscription | `stripe.subscriptions.create()` | Use `payment_behavior: 'default_incomplete'` for SCA |
25| Update subscription | `stripe.subscriptions.update()` | Set `proration_behavior` explicitly |
26| Cancel subscription | `stripe.subscriptions.cancel()` | Use `prorate: true` to credit unused time |
27| Customer Portal | `stripe.billingPortal.sessions.create()` | Self-service billing management, returns short-lived URL |
28| Webhook verify | `stripe.webhooks.constructEvent()` | Requires raw body, signature header, and endpoint secret |
29| Elements provider | `<Elements stripe={stripePromise} options={options}>` | Wraps payment components, pass `clientSecret` or `mode` |
30| PaymentElement | `<PaymentElement />` | Renders all supported payment methods automatically |
31| Retrieve + expand | `stripe.checkout.sessions.retrieve(id, { expand })` | Expand nested objects to reduce API calls |
32| Search | `stripe.paymentIntents.search({ query })` | Stripe Query Language for filtering |
33
34## Common Mistakes
35
36| Mistake | Correct Pattern |
37| ------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
38| Parsing webhook body as JSON before verification | Use `express.raw({ type: 'application/json' })` to pass raw body to `constructEvent` |
39| Hardcoding payment method types | Use `automatic_payment_methods` or let Checkout choose based on currency and region |
40| Creating PaymentIntent client-side | Create on server, pass only `client_secret` to client |
41| Not awaiting `elements.submit()` before confirm | Call `elements.submit()` first to trigger validation, then `confirmPayment` |
42| Missing `return_url` in `confirmPayment` | Always provide `return_url` for redirect-based payment methods |
43| Using test keys in production | Store keys in environment variables, validate `STRIPE_SECRET_KEY` prefix (`sk_live_` vs `sk_test_`) |
44| Not handling `requires_action` status | Check PaymentIntent status after confirmation, handle 3D Secure or other authentication |
45| Creating Customer Portal session without settings | Save portal settings in Dashboard first, otherwise API returns an error |
46| Not expanding related objects | Use `expand` parameter to include nested objects like `latest_invoice.payment_intent` |
47| Ignoring webhook idempotency | Use `event.id` to deduplicate, webhook events can be delivered more than once |
48
49## Delegation
50
51- **Payment flow architecture**: Use `Explore` agent to discover integration patterns
52- **Webhook debugging**: Use `Task` agent for end-to-end event tracing
53- **Code review**: Delegate to `code-reviewer` agent for security review of payment handlers
54
55## References
56
57- [Checkout Sessions, Payment Intents, and one-time payments](references/checkout-and-payments.md)
58- [Subscription lifecycle, pricing models, trials, and Customer Portal](references/subscriptions.md)
59- [Webhook endpoints, signature verification, and event handling](references/webhooks.md)
60- [React Stripe.js, Elements provider, PaymentElement, and custom forms](references/stripe-elements.md)
oakoss