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)