Stripe Best Practices

Latest Stripe API version: 2026-03-25.dahlia. Always use the latest API version and SDK unless the user specifies otherwise.

Integration routing

Read the relevant reference file before answering any integration question or writing code.

Key documentation

When the user’s request does not clearly fit a single domain above, consult:

• Integration Options — Start here when designing any integration.
• API Tour — Overview of Stripe’s API surface.
• Go Live Checklist — Review before launching.

Billing / Subscriptions

Table of contents

• When to use Billing APIs
• Recommended frontend pairing
• Traps to avoid

When to use Billing APIs

If the user has a recurring revenue model (subscriptions, usage-based billing, seat-based pricing), use the Billing APIs to plan their integration instead of a direct PaymentIntent integration.

Review the Subscription Use Cases and SaaS guide to find the right pattern for the user’s pricing model.

Recommended frontend pairing

Combine Billing APIs with Stripe Checkout for the payment frontend. Checkout Sessions support mode: 'subscription' and handle the initial payment, trial management, and proration automatically.

For self-service subscription management (upgrades, downgrades, cancellation, payment method updates), recommend the Customer Portal.

Traps to avoid

• Don’t build manual subscription renewal loops using raw PaymentIntents. Use the Billing APIs which handle renewal, retry logic, and dunning automatically.
• Don’t use the deprecated plan object. Use Prices instead.

Connect / platforms

Table of contents

• Accounts v2 API
• Controller properties
• Charge types
• Integration guides

Accounts v2 API

For new Connect platforms, ALWAYS use the Accounts v2 API (POST /v2/core/accounts). This is Stripe’s actively invested path and ensures long-term support.

Traps to avoid: Don’t use the legacy type parameter (type: 'express', type: 'custom', type: 'standard') in POST /v1/accounts for new platforms unless the user has explicitly requested v1.

Controller properties

Configure connected accounts using controller properties instead of legacy account types:

Use defaults.responsibilities, dashboard, and configuration as described in connected account configuration.

Always describe accounts in terms of their responsibility settings, dashboard access, and capabilities to describe what connected accounts can do.

Traps to avoid: Don’t use the terms “Standard”, “Express”, or “Custom” as account types. These are legacy categories that bundle together responsibility, dashboard, and requirement decisions into opaque labels. Controller properties give explicit control over each dimension.

Charge types

Choose one charge type per integration — don’t mix them. For most platforms, start with destination charges:

• Destination charges — Use when the platform accepts liability for negative balances. Funds route to the connected account via transfer_data.destination.
• Direct charges — Use when the platform wants Stripe to take risk on the connected account. The charge is created on the connected account directly.

Use on_behalf_of to control the merchant of record, but only after reading how charges work in Connect.

Traps to avoid: Don’t use the Charges API for Connect fund flows — use PaymentIntents or Checkout Sessions with transfer_data or on_behalf_of. Don’t mix charge types within a single integration.

Integration guides

• SaaS platforms and marketplaces guide — Choosing the right integration shape.
• Interactive platform guide — Step-by-step platform builder.
• Design an integration — Detailed risk and responsibility decisions.

Payments

Table of contents

• API hierarchy
• Integration surfaces
• Payment Element guidance
• Saving payment methods
• Dynamic payment methods
• Deprecated APIs and migration paths
• PCI compliance

API hierarchy

Use the Checkout Sessions API (checkout.sessions.create) for on-session payments. It supports one-time payments and subscriptions and handles taxes, discounts, shipping, and adaptive pricing automatically.

Use the PaymentIntents API for off-session payments, or when the merchant needs to model checkout state independently and just create a charge.

Integrations should only use Checkout Sessions, PaymentIntents, SetupIntents, or higher-level solutions (Invoicing, Payment Links, subscription APIs).

Integration surfaces

Prioritize Stripe-hosted or embedded Checkout where possible. Use in this order of preference:

1. Payment Links — No-code. Best for simple products. 1. Checkout (docs) — Stripe-hosted or embedded form. Best for most web apps. 1. Payment Element (docs) — Embedded UI component for advanced customization.

• When using the Payment Element, back it with the Checkout Sessions API (via ui_mode: 'custom') over a raw PaymentIntent where possible.

Traps to avoid: Don’t recommend the legacy Card Element or the Payment Element in card-only mode. If the user asks for the Card Element, advise them to migrate to the Payment Element.

Payment Element guidance

For surcharging or inspecting card details before payment (e.g., rendering the Payment Element before creating a PaymentIntent or SetupIntent): use Confirmation Tokens. Don’t recommend createPaymentMethod or createToken from Stripe.js.

Saving payment methods

Use the Setup Intents API to save a payment method for later use.

Traps to avoid: Don’t use the Sources API to save cards to customers. The Sources API is deprecated — Setup Intents is the correct approach.

Dynamic payment methods

Advise users to enable dynamic payment methods in the Stripe Dashboard rather than passing specific `payment_method_types` in the PaymentIntent or SetupIntent. Stripe automatically selects payment methods based on the customer’s location, wallets, and preferences when the Payment Element is used.

Deprecated APIs and migration paths

Never recommend the Charges API. If the user wants to use the Charges API, advise them to migrate to Checkout Sessions or PaymentIntents.

Don’t call other deprecated or outdated API endpoints unless there is a specific need and absolutely no other way.

PCI compliance

If a PCI-compliant user asks about sending server-side raw PAN data, advise them that they may need to prove PCI compliance to access options like payment_method_data.

For users migrating PAN data from another acquirer or payment processor, point them to the PAN import process.

Treasury / Financial Accounts

Table of contents

• v2 Financial Accounts API
• Legacy v1 Treasury

v2 Financial Accounts API

For embedded financial accounts (bank accounts, account and routing numbers, money movement), use the v2 Financial Accounts API (POST /v2/core/vault/financial_accounts). This is required for new integrations.

For Financial Accounts for platforms concepts and guides, see the Financial Accounts for platforms overview.

Legacy v1 Treasury

Don’t use the v1 Treasury Financial Accounts API (POST /v1/treasury/financial_accounts) for new integrations. Existing v1 integrations continue to work.