Skip to content
Stripe Best Practices

Stripe Best Practices

by Stripe
MIT
Repository Docs
markdown Development
stripepaymentsbillingsubscriptionsconnecttax

Summary

Stripe's official agent skill for choosing the right payments primitive — Checkout vs PaymentIntents, Connect, Billing, Tax — and for handling API keys and webhooks safely.

Features

  • Guidance on Checkout Sessions vs PaymentIntents and the Payment Element
  • Connect platform setup on Accounts v2 including controller properties
  • Billing, subscription and proration patterns
  • Stripe Tax, automatic_tax, product tax codes and registrations
  • Defaults to restricted API keys over secret keys
  • Webhook signature verification and OAuth guidance
  • Pins the current Stripe API version and SDK releases

Install This Skill

Add this skill to your favorite AI agent in a few steps.

Any AI agent

This skill is plain instructions — it works with any assistant that accepts custom instructions or system prompts.

  1. Copy the skill content with the button below.
  2. Paste it into your agent's instruction file or system prompt (for example AGENTS.md, .cursorrules, or a custom instructions field).
  3. Ask the agent to apply the skill whenever the task matches.

Skill Content

Markdown Content

Copy this content and use it with your preferred AI agent

---
name: stripe-best-practices
description: >-
  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.

---

Latest Stripe API version: **2026-07-29.dahlia**. Always use the latest API version and SDK unless the user specifies otherwise.

Latest SDK versions:

| 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)](https://docs.stripe.com/keys/restricted-api-keys.md) (`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](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).

- *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`.

- 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](https://docs.stripe.com/payments/payment-methods/integration-options.md) — Start here when designing any integration.
- [API Tour](https://docs.stripe.com/payments-api/tour.md) — Overview of Stripe’s API surface.
- [Go Live Checklist](https://docs.stripe.com/get-started/checklist/go-live.md) — Review before launching.

Usage Instructions

Learn how to use this skill with different AI agents.

Generic Instructions
npx skills add https://github.com/stripe/ai --skill stripe-best-practices

Example Usage

Add a subscription checkout flow with Stripe Tax enabled for EU VAT, and review my webhook handler for signature verification.

Description

Most Stripe mistakes are not syntax errors; they are architectural choices made early and discovered late. This official skill from Stripe front-loads those decisions so an agent proposes the right primitive before writing any code.

It covers the choices that matter most:

  • Integration surface — Checkout Sessions versus PaymentIntents with the Payment Element, and when a hosted page beats an embedded form.
  • Connect — platform and marketplace setup on Accounts v2, including controller properties, which determine who owns fees, losses and the dispute relationship.
  • Billing — subscriptions, plan changes and proration.
  • Tax — Stripe Tax, automatic_tax, product tax codes and registrations for sales tax, VAT and GST.
  • Treasury — financial accounts for embedded finance.
  • Migrations — moving off deprecated Stripe APIs onto current equivalents.

The security guidance is unusually concrete for a vendor skill. It tells the agent to recommend a restricted API key (rk_ prefix) over a full secret key (sk_) by default, and covers webhook signature verification and OAuth for platform integrations — the failure modes that turn into incidents rather than bugs.

The skill also pins the current API version and SDK releases (as published, 2026-07-29.dahlia) and instructs the agent to use the latest unless you say otherwise, which stops a model from generating a shape of request that was current in its training data but has since moved on. Stripe regenerates the file from its own documentation, so the pinned versions track releases.

Install: npx skills add https://github.com/stripe/ai --skill stripe-best-practices. It lives in Stripe's stripe/ai repository alongside their other AI tooling, under the MIT licence, and activates whenever an agent is building, changing or reviewing a Stripe integration.

Related Skills

Skill: Auth0 Agent Skill

by Auth0

New

Auth0's official agent skill: a router that detects your framework and intent, then loads the right Auth0 guidance for login, MFA, Organizations, tenant audits, debugging or provider migration.

Development

Skill: Redis Search

by Redis, Inc.

New

Redis' own guidance for FT.CREATE schema design, FT.SEARCH / FT.AGGREGATE / FT.HYBRID, HNSW vector similarity and RAG retrieval pipelines.

Development

Skill: Supabase

by Supabase

New

Supabase's official skill covering Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron and Queues — with a hard rule to verify against the live changelog before writing code.

Development

Skill: GSAP ScrollTrigger

by GreenSock

New

GreenSock's official ScrollTrigger skill — scroll-linked animation, pinning, scrub and trigger positioning, with the exact start/end syntax agents get wrong.

DevelopmentDesign & Creative
1 views
Browse all skills →