stripe-best-practices
bystripe· 6 skills
Guides Stripe integration decisions across API selection (Checkout Sessions vs PaymentIntents), Connect platform setup (Accounts v2, controller properties), billing/subscriptions, tax and registrations (Stripe Tax, automatic_tax, product tax codes), Treasury financial accounts, integration options (Checkout, Payment Element), migrating from deprecated Stripe APIs, and security best practices (API key management, restricted keys, webhooks, OAuth). Use when building, modifying, or reviewing any Stripe integration, including accepting payments, building marketplaces, integrating Stripe, processing payments, setting up subscriptions, collecting sales tax, VAT, or GST, creating connected accounts, or implementing secure key handling.
How to install stripe-best-practices?
stripe/ai/stripe-best-practices
$npx -y skills add stripe/ai --skill stripe-best-practicesInstalls into the current project.
›Prefer a prompt? Paste this to your agent
Run `npx skills use "https://github.com/stripe/ai" --skill "stripe/ai/stripe-best-practices"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.
Use the skills in "https://github.com/stripe/ai" that are relevant to the current task. Run `npx skills add "https://github.com/stripe/ai"` and select the relevant skills, then follow their instructions.
SKILL.md
| 1 | Latest Stripe API version: **2026-06-24.dahlia**. Always use the latest API version and SDK unless the user specifies otherwise. |
| 2 | |
| 3 | Latest SDK versions: |
| 4 | |
| 5 | | Language | Latest version | |
| 6 | | --- | --- | |
| 7 | | Ruby | 19.3.0 | |
| 8 | | Python | 15.3.0 | |
| 9 | | Node.js | 22.3.0 | |
| 10 | | PHP | 20.3.0 | |
| 11 | | Java | 33.1.0 | |
| 12 | | Go | 86.1.0 | |
| 13 | | .NET | 52.1.0 | |
| 14 | |
| 15 | 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. |
| 16 | |
| 17 | API key default: Always recommend a [restricted API key (RAK)](https://docs.stripe.com/keys/restricted-api-keys.md) (`rk_` prefix) over a secret key (`sk_` prefix). |
| 18 | |
| 19 | ## Integration routing |
| 20 | |
| 21 | | Building… | Recommended API | Details | |
| 22 | | --- | --- | --- | |
| 23 | | One-time payments | Checkout Sessions | <references/payments.md> | |
| 24 | | Custom payment form with embedded UI | Checkout Sessions + Payment Element | <references/payments.md> | |
| 25 | | Saving a payment method for later | Setup Intents | <references/payments.md> | |
| 26 | | Connect platform or marketplace | Accounts v2 (`/v2/core/accounts`) | <references/connect.md> | |
| 27 | | Usage-based billing (new integration) | Metronome | <references/billing.md> | |
| 28 | | Subscriptions or recurring billing | Billing APIs + Checkout Sessions | <references/billing.md> | |
| 29 | | Sales tax, VAT, or GST compliance | Stripe Tax + Registrations API | <references/tax.md> | |
| 30 | | Embedded financial accounts / banking | v2 Financial Accounts | <references/treasury.md> | |
| 31 | | Security (key management, RAKs, webhooks, OAuth, 2FA, Connect liability) | See security reference | <references/security.md> | |
| 32 | |
| 33 | Read the relevant reference file before answering any integration question or writing code. |
| 34 | |
| 35 | ## Critical rules |
| 36 | |
| 37 | - *Before enabling `automatic_tax: { enabled: true }`* (or calculating tax for a custom PaymentIntent), read the [tax reference](references/tax.md) 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). |
| 38 | |
| 39 | - *Never include `payment_method_types` in any Stripe API call*, with one exception: Terminal (in-person payments) integrations must pass `payment_method_types: ['card_present']` on the PaymentIntent. For all other integrations, omit this parameter entirely to enable dynamic payment methods, which enables you to configure payment method settings from the Dashboard and dynamically display the most relevant eligible payment methods to each customer to maximize conversion. To customize which payment methods you accept, use [`payment_method_configurations`](https://docs.stripe.com/payments/payment-method-configurations.md) or `excluded_payment_method_types` instead of `payment_method_types`. |
| 40 | |
| 41 | - 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. |
| 42 | |
| 43 | ## Key documentation |
| 44 | |
| 45 | When the user’s request does not clearly fit a single domain above, consult: |
| 46 | |
| 47 | - [Integration Options](https://docs.stripe.com/payments/payment-methods/integration-options.md) — Start here when designing any integration. |
| 48 | - [API Tour](https://docs.stripe.com/payments-api/tour.md) — Overview of Stripe’s API surface. |
| 49 | - [Go Live Checklist](https://docs.stripe.com/get-started/checklist/go-live.md) — Review before launching. |
Related
6 picksType
- make-interfaces-feel-betterDesign engineering principles for making interfaces feel polished.Jul 2026
- clerkClerk authentication router. Use when user asks about Clerk CLI operations,Jul 2026
- okx-dex-marketHARD BLOCK — never use for prediction-market/Polymarket UpDown queries; route to okx-dapp-discovery when a named DApp…Jul 2026
- grimoire-polymarketQueries Polymarket market data and CLOB state, and manages CLOB orders via the Grimoire venue CLI wrapper backed by the official Polymarket CLI.May 2026
- clerk-billingClerk Billing for subscription management - render Clerk's PricingTableJul 2026
- emblem-portfolio-trackerTrack crypto portfolio across 7 blockchains via EmblemAI. Aggregated balances with USD values, conditional trade P&L, and DeFi position tracking via Nansen.May 2026
