stripe-best-practices

stripe/ai

Guides Stripe integration decisions and security best practices for payments, Connect, billing, and Treasury.

What is stripe-best-practices?

This skill provides guidance on Stripe API selection, platform setup, billing/subscriptions, and security practices. Use it when building, modifying, or reviewing any Stripe integration—from accepting payments to setting up marketplaces and implementing secure key handling.

Routes to correct Stripe APIs (Checkout Sessions, PaymentIntents, Setup Intents, Accounts v2)
Advises on Connect platform setup, controller properties, and marketplace architecture
Guides subscription and recurring billing configuration
Covers Treasury financial accounts and embedded banking
Recommends security practices: restricted API keys, webhook validation, OAuth, and key management
Helps migrate from deprecated Stripe APIs

How to install stripe-best-practices

npx skills add null --skill stripe-best-practices

Prerequisites

Stripe account (or use `stripe sandbox create` via Stripe CLI for testing)
Stripe CLI installed (`npm i -g @stripe/cli`) for sandbox key generation
Stripe MCP server configured at `https://mcp.stripe.com` for tailored integration planning (optional but recommended)

Claude Code

Cursor

Windsurf

Cline

How to use stripe-best-practices

1.Install Stripe CLI and generate sandbox keys if needed: `npm i -g @stripe/cli && stripe sandbox create`
2.Configure Stripe MCP server at `https://mcp.stripe.com` for integration planning
3.Call `stripe_implementation_planner` with your business description to get a tailored integration guide
4.Consult the integration routing table to identify the correct API for your use case (Checkout Sessions, PaymentIntents, Setup Intents, Accounts v2, etc.)
5.Review the relevant reference documentation (payments, connect, billing, tax, treasury, or security)
6.Always use restricted API keys (`rk_` prefix) instead of secret keys (`sk_` prefix)
7.Omit `payment_method_types` from API calls (except Terminal integrations) to enable dynamic payment methods
8.Test with the latest Stripe API version (2026-06-24.dahlia) unless otherwise specified

Use cases

Good for

Building a one-time payment flow with Checkout Sessions or Payment Element
Setting up a marketplace with Stripe Connect and Accounts v2
Implementing usage-based or subscription billing with the Billing APIs
Configuring sales tax compliance with Stripe Tax and Registrations API
Securing payment integrations with restricted API keys and webhook validation

Who it's for

Backend engineers building payment systems
Full-stack developers integrating Stripe into applications
Marketplace and platform builders using Stripe Connect
DevOps/security teams managing API key rotation and OAuth flows
Product teams reviewing payment architecture decisions

stripe-best-practices FAQ

Should I use Checkout Sessions or PaymentIntents?

Use Checkout Sessions for one-time payments and custom payment forms with Payment Element. Use PaymentIntents only when you need lower-level control. Checkout Sessions handle more complexity automatically.

What API should I use for a marketplace or platform?

Use Accounts v2 (`/v2/core/accounts`) for Stripe Connect platforms and marketplaces. Consult the Connect reference for controller properties and liability setup.

How do I handle subscriptions and recurring billing?

Use the Billing APIs combined with Checkout Sessions. For new usage-based billing integrations, consider Metronome. See the billing reference for detailed guidance.

What's the difference between restricted API keys and secret keys?

Restricted API keys (`rk_` prefix) limit access to specific resources and actions, improving security. Always use them instead of secret keys (`sk_` prefix) unless you have a specific reason not to.

Do I need to specify payment_method_types in my API calls?

No—omit this parameter to enable dynamic payment methods, which automatically display the most relevant payment methods to each customer. The only exception is Terminal (in-person) integrations, which must pass `payment_method_types: ['card_present']`.

Full instructions (SKILL.md)

Source of truth, from stripe/ai.

name: stripe-best-practices description: >- Guides Stripe integration decisions — API selection (Checkout Sessions vs PaymentIntents), Connect platform setup (Accounts v2, controller properties), billing/subscriptions, Treasury financial accounts, integration surfaces (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, creating connected accounts, or implementing secure key handling.

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

If you do not 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.

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

Stripe MCP

Install the Stripe MCP server before writing payment or billing code so stripe_implementation_planner is available. Use URL https://mcp.stripe.com. See /mcp for client setup.

Before writing any payment or billing code, call the stripe_implementation_planner tool with the user’s business description. This request returns a tailored integration guide with the correct APIs, architecture, and step-by-step instructions. If MCP isn’t configured, use the routing table below instead. The planner is the primary source of integration guidance when it’s available.

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

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 or excluded_payment_method_types instead of payment_method_types.