Stripe Best Practices
Best practices for building Stripe payment integrations
Keywords
stripe, payment, checkout, subscription, billing
Intents
- integrate payment processing
- handle subscriptions
- process credit cards
Constraints
Never
- Charges API
- Sources API
- Card Element
- Payment Element in card-only mode
- Tokens API (unless specific need)
- mixing Connect charge types
- legacy Connect terms (Standard/Express/Custom)
Always
- latest API/SDK version (unless specified otherwise)
- advise PCI compliance proof for raw PAN handling
- use controller properties for Connect (not legacy terms)
Preferences
- Prefer CheckoutSessions over PaymentIntents when on-session payments
- Prefer Stripe-hosted Checkout over embedded Checkout when default choice
- Prefer embedded Checkout over Payment Element when more control needed
- Prefer dynamic payment methods over explicit payment_method_types when using Payment Element
- Prefer SetupIntents over Sources when saving payment methods
- Prefer Confirmation Tokens over createPaymentMethod/createToken when inspecting card before payment
- Prefer Billing APIs over raw PaymentIntents when subscriptions/recurring
- Prefer direct charges over destination charges when platform wants Stripe to take risk
- Prefer destination charges over direct charges when platform accepts liability
Decisions
- When user wants Charges API: advise migration to CheckoutSessions or PaymentIntents
- When user wants Card Element: advise migration to Payment Element
- When recurring revenue / subscription / SaaS: recommend Billing APIs + Checkout frontend
- When platform / marketplace / Connect: follow integration recommendations, use controller properties
- When migrating PAN data from another processor: point to migration process
- When render Payment Element before creating intent: use Confirmation Tokens
References
- stripe:integration-options - primary integration design reference
- stripe:api-tour - API overview
- stripe:go-live - pre-launch checklist
- stripe:migration/charges - Charges to PaymentIntents migration
- stripe:migration/payment-element - Card Element to Payment Element migration
- stripe:billing/design-integration - subscription integration planning
- stripe:connect/recommendations - Connect charge type selection
- stripe:pan-import - PAN data migration
Converted from UASP format (knowledge skill)