stripe-best-practices_skill

Overview

This skill provides concise best practices for designing and building Stripe integrations focused on modern APIs, secure flows, and recommended front-end patterns. It prioritizes CheckoutSessions, Billing, and newer integration surfaces while flagging deprecated or discouraged approaches. Use it to align payments work with Stripe's current guidance and go-live checklist.

How this skill works

The skill inspects integration goals (one-time vs subscription, on-session vs off-session, platform vs single merchant) and maps them to the correct Stripe APIs and UI surfaces. It recommends defaults such as the latest API/SDK versions, Stripe-hosted Checkout, dynamic payment methods, and Billing APIs for recurring use cases. It warns about deprecated endpoints and unsafe patterns and suggests migration or alternatives where relevant.

When to use it

• Choosing between CheckoutSessions, PaymentIntents, or Billing for a new payment flow.
• Designing SaaS subscriptions, metered billing, or recurring revenue models.
• Building a marketplace or platform requiring fund routing with Connect.
• Evaluating front-end options: Stripe-hosted Checkout, Payment Element, or embedded forms.
• Planning a PCI scope reduction or deciding how to save payment methods securely.

Best practices

• Default to the latest Stripe API and SDK versions unless there’s a clear reason not to.
• Prioritize CheckoutSessions for on-session payments and subscriptions; use PaymentIntents for off-session or custom checkout state.
• Use Stripe-hosted Checkout or embedded Checkout where possible; use the Payment Element only for advanced customization.
• Never recommend legacy Charges API, Sources API, or Tokens; advise migration to CheckoutSessions or PaymentIntents when needed.
• Enable dynamic payment methods in the dashboard instead of hard-coding payment_method_types.
• For saving cards, use SetupIntents; for rendering card input before creating intents, use Stripe Confirmation Tokens rather than createToken/createPaymentMethod.

Example use cases

• SaaS subscription signup: combine Billing APIs with Checkout to handle trials, plans, and invoicing.
• One-time digital purchase: use CheckoutSessions to model taxes, discounts, and capture payment in a hosted flow.
• Marketplace payout routing: choose direct or destination charges per risk model and use on_behalf_of for merchant of record.
• Off-session recurring charge (e.g., subscription renewal): use PaymentIntents for background charges with saved payment methods.
• PCI-sensitive migration: follow Stripe’s PAN import guidance and require proof of PCI compliance for server-side raw PAN access.