stripe-best-practices

# 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](...