Skip to content
Stripe Best Practices

Stripe Best Practices Skill

by Stripe stripe/ai skills/stripe-best-practices

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.

GitHub Docs
Development
Released
MIT

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from stripe/ai.

$ npx skills add stripe/ai --skill stripe-best-practices

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

Copy the whole skill folder — SKILL.md and any scripts or references beside it — into ~/.claude/skills/stripe-best-practices/, where Claude Code picks it up in every project. Only git is needed.

tmp=$(mktemp -d) && \
  git clone --depth 1 --branch main https://github.com/stripe/ai.git "$tmp" && \
  mkdir -p ~/.claude/skills && \
  cp -R "$tmp"/skills/stripe-best-practices ~/.claude/skills/stripe-best-practices

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/stripe-best-practices/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/
Open folder on GitHub

About

  • 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

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-08-26.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.

Try it

Once installed, ask your agent something like:

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

SKILL.md

The instructions your agent loads, as published by Stripe.

SKILL.md
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-08-26.dahlia. Always use the latest API version and SDK unless the user specifies otherwise.

Latest SDK versions:

LanguageLatest version
Ruby19.4.0
Python15.4.0
Node.js22.4.0
PHP21.1.0
Java33.2.0
Go86.2.0
.NET52.2.0

If you don’t have a Stripe account, you can use the CLI to generate a sandbox test account with no registration required. Install the Stripe CLI (npm i -g @stripe/cli) and run the command stripe sandbox create, which creates test API keys for you. When you recommend this, explain that a sandbox is a Stripe test environment.

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 APIDetails
One-time paymentsCheckout Sessions<references/payments.md>
Custom payment form with embedded UICheckout Sessions + Payment Element<references/payments.md>
Saving a payment method for laterSetup Intents<references/payments.md>
Connect platform or marketplaceAccounts v2 (/v2/core/accounts)<references/connect.md>
Usage-based billing (new integration)Metronome<references/billing.md>
Subscriptions or recurring billingBilling APIs + Checkout Sessions<references/billing.md>
Sales tax, VAT, or GST complianceStripe Tax + Registrations API<references/tax.md>
Embedded financial accounts / bankingv2 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` or excluded_payment_method_types instead of payment_method_types.
  • Never present webhooks as optional. We recommend webhooks for every payment integration and they’re required for subscriptions and asynchronous payment methods. Fulfillment belongs in a handler for both checkout.session.completed and checkout.session.async_payment_succeeded (gated on payment_status), not the success page. See <references/payments.md>.
  • 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:

Install

Covered in the Weekly

Related Skills

See all Stripe Best Practices alternatives

Skill: Coinbase Agentic Wallet

by Coinbase

Coinbase's official skill for driving a crypto wallet from an agent: balances and transfers on Base, Polygon and Solana, plus paying for and monetising x402 APIs.

Development

Skill: GoLive

by mikehasa

Open-source agent skill that takes an AI-built app live on your own accounts: hosting, database, domain, email and payments, with a plan-and-approve workflow.

DevOps & Infrastructure

Skill: geo-sleuth

by Oldcircle

Featured

Find where a photo was taken: EXIF, OCR, OpenStreetMap, skyline and satellite matching, with coordinates, error radius and evidence images.

Development
1373 views 450 copies
Browse all skills →