SKILL.md
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 paymentbehavior: 'defaultincomplete' 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 automaticpaymentmethods 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 STRIPESECRETKEY prefix (sklive vs sktest) |
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 latestinvoice.paymentintent |
| Ignoring webhook idempotency | Use event.id to deduplicate, webhook events can be delivered more than once |
Delegation
- Payment flow architecture: Use
Exploreagent to discover integration patterns - Webhook debugging: Use
Taskagent for end-to-end event tracing - Code review: Delegate to
code-revieweragent for security review of payment handlers
References
- [Checkout Sessions, Payment Intents, and one-time payments](references/checkout-and-payments.md)
- [Subscription lifecycle, pricing models, trials, and Customer Portal](references/subscriptions.md)
- [Webhook endpoints, signature verification, and event handling](references/webhooks.md)
- [React Stripe.js, Elements provider, PaymentElement, and custom forms](references/stripe-elements.md)