stripe-best-practices

In Core, read packages/api/src/stripe/api-version.ts and packages/api/package.json for the approved API version and SDK. Reuse the existing Stripe client. Preserve those pins unless the requested work explicitly includes a reviewed version upgrade; choose and verify that upgrade target before changing code. The upstream versions and examples below are reference snapshots, not Core upgrade instructions.

Upstream API reference snapshot: 2026-07-29.dahlia.

Upstream SDK reference snapshots (Core uses its approved manifest and lockfile):

Language	Latest version
Ruby	19.4.0
Python	15.4.0
Node.js	22.4.0
PHP	21.1.0
Java	33.2.0
Go	86.2.0
.NET	52.2.0

If you don’t have a Stripe account, you can call a CLI command to generate working API keys with no registration required. You can install the Stripe CLI (npm i -g @stripe/cli) and run the command stripe sandbox create to get started.

If stripe sandbox create is used, don’t use MCP.

If you try to use MCP after running sandbox creation, first make sure stripe sandbox claim is run. Use stripe whoami --format json for CLI auth checks; do not run stripe config --list.

API key default: Always recommend a restricted API key (RAK) (rk_ prefix) over a secret key (sk_ prefix).

Integration routing

Building…	Recommended API	Details
One-time payments	Checkout Sessions	<references/payments.md>
Custom payment form with embedded UI	Checkout Sessions + Payment Element	<references/payments.md>
Saving a payment method for later	Setup Intents	<references/payments.md>
Connect platform or marketplace	Accounts v2 (/v2/core/accounts)	<references/connect.md>
Usage-based billing (new integration)	Metronome	<references/billing.md>
Subscriptions or recurring billing	Billing APIs + Checkout Sessions	<references/billing.md>
Sales tax, VAT, or GST compliance	Stripe Tax + Registrations API	<references/tax.md>
Embedded financial accounts / banking	v2 Financial Accounts	<references/treasury.md>
Security (key management, RAKs, webhooks, OAuth, 2FA, Connect liability)	See security reference	<references/security.md>

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

Critical rules

• Before enabling automatic_tax: { enabled: true } (or calculating tax for a custom PaymentIntent), read the tax reference and confirm the user has an active registration. Without one, Stripe calculates and collects no tax while the user believes tax is on (the most common Stripe Tax mistake).

• Preserve Core's quoted payment method. packages/api/src/donate/payment-intent.ts intentionally passes payment_method_types when the gift quote binds the allowed method (including card versus ACH fee assumptions). Keep that allowlist and its idempotent recovery behavior. The same helper enables automatic_payment_methods only when no method restriction is supplied. Do not replace this contract with Dashboard-driven dynamic methods during unrelated work. For a new integration, verify the supported options in the pinned SDK and PaymentIntent creation API.

• On API version 2026-03-25.dahlia or later, pass the parameter integration_identifier to checkout.sessions.create to tag sessions with a custom label for tracking and comparing checkout flows in the Dashboard. The label should include a suffix of 8 random letters.

• Always instantiate a StripeClient and call methods on that instance. Do not use the deprecated global/module-level API key pattern (stripe.api_key = …, Stripe.setApiKey, stripe.Key = …, StripeConfiguration.ApiKey = …). The global pattern is deprecated in all current SDKs.

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.