Stripe integration best practices

Keeps Stripe code on current APIs: Checkout Sessions, Accounts v2, Billing and Stripe Tax, mandatory webhooks, no payment_method_types, restricted keys. Use when building, changing or reviewing any Stripe integration.

CodingPack: Stripe skills79 linesstripe-best-practices
Author
Source
stripe/ai/skills/stripe-best-practices @ 119bc4a
License
MIT · Copyright (c) 2024–2025 Stripe

About this skill

What it does

Stripe's best-practices skill steers an agent's Stripe integration decisions toward the APIs Stripe currently recommends. SKILL.md pins the latest API version (2026-11-18.endive in our copy) and SDK versions for seven languages, then routes each kind of work to a reference the agent must read before answering: payments.md (Checkout Sessions, Payment Element, fulfillment, deprecated APIs), billing.md (subscriptions, Metronome for usage billing), connect.md (Accounts v2), tax.md (Stripe Tax), treasury.md (v2 Financial Accounts) and security.md.

A few rules recur across files. Do not pass payment_method_types, except card_present for Terminal. Webhooks are never optional: fulfil from checkout.session.completed and checkout.session.async_payment_succeeded, gated on payment_status, not from the success page. automatic_tax collects nothing, and raises no error, without an active registration. One rule lives only in SKILL.md: use a StripeClient instance, not a global key. The security reference prefers restricted keys (rk_) to secret keys (sk_) and adds a vault per cloud, a regex for live keys in code, a pre-commit hook, a six-step move to restricted keys, IP access policies, OAuth state and 2FA.

New work goes to separate sandboxes, not the shared test mode, and stripe sandbox create makes one without an account. With the Stripe CLI or MCP connected, the agent checks tax itself through taxability_reason; in live mode it previews an invoice instead of running paid tax calculations.

When to use it, and when not

Use it whenever an agent writes, changes or reviews Stripe code.

The version numbers date from our pinned copy; check them against Stripe's current docs. Usage-based billing is handed to a metronome skill that is not in our catalog; the text gives its address on docs.stripe.com.

How to run it

The install command below puts SKILL.md, the six references and the licence in place. Stripe's repository packages the same skills for several agents under providers/; our copy comes from skills/.

  • Claude Code: /stripe-best-practices, or ask for the skill by name.
  • Codex: $stripe-best-practices.
  • Cursor: type / in the Agent chat and pick stripe-best-practices.

Example: /stripe-best-practices Review our subscription checkout in src/billing: webhooks, tax and how the keys are stored.

How it differs from similar skills

Stripe implementation planner from the same pack picks products for a new setup with stripe tools plan and sends debugging, upgrades and code changes here. Stripe Apps builds apps inside the Stripe Dashboard. No other skill in our catalog covers payments. Env and config audit hunts hardcoded secrets in any repository; the security rules here are Stripe's own, down to key prefixes and webhook signatures.

Install

Run one command — it saves SKILL.md and the files it uses into your agent's skills folder. Claude Code and Codex pick up a new skill without a restart; if it does not show up, restart the agent.

Claude Code — macOS, Linux
curl -fsSL --create-dirs -o ~/.claude/skills/stripe-best-practices/SKILL.md https://anymodel.org/en/skills/stripe/stripe-best-practices/SKILL.md -o ~/.claude/skills/stripe-best-practices/LICENSE https://anymodel.org/en/skills/stripe/stripe-best-practices/LICENSE -o ~/.claude/skills/stripe-best-practices/references/billing.md https://anymodel.org/en/skills/stripe/stripe-best-practices/references/billing.md -o ~/.claude/skills/stripe-best-practices/references/connect.md https://anymodel.org/en/skills/stripe/stripe-best-practices/references/connect.md -o ~/.claude/skills/stripe-best-practices/references/payments.md https://anymodel.org/en/skills/stripe/stripe-best-practices/references/payments.md -o ~/.claude/skills/stripe-best-practices/references/security.md https://anymodel.org/en/skills/stripe/stripe-best-practices/references/security.md -o ~/.claude/skills/stripe-best-practices/references/tax.md https://anymodel.org/en/skills/stripe/stripe-best-practices/references/tax.md -o ~/.claude/skills/stripe-best-practices/references/treasury.md https://anymodel.org/en/skills/stripe/stripe-best-practices/references/treasury.md
Codex, Cursor — macOS, Linux
curl -fsSL --create-dirs -o ~/.agents/skills/stripe-best-practices/SKILL.md https://anymodel.org/en/skills/stripe/stripe-best-practices/SKILL.md -o ~/.agents/skills/stripe-best-practices/LICENSE https://anymodel.org/en/skills/stripe/stripe-best-practices/LICENSE -o ~/.agents/skills/stripe-best-practices/references/billing.md https://anymodel.org/en/skills/stripe/stripe-best-practices/references/billing.md -o ~/.agents/skills/stripe-best-practices/references/connect.md https://anymodel.org/en/skills/stripe/stripe-best-practices/references/connect.md -o ~/.agents/skills/stripe-best-practices/references/payments.md https://anymodel.org/en/skills/stripe/stripe-best-practices/references/payments.md -o ~/.agents/skills/stripe-best-practices/references/security.md https://anymodel.org/en/skills/stripe/stripe-best-practices/references/security.md -o ~/.agents/skills/stripe-best-practices/references/tax.md https://anymodel.org/en/skills/stripe/stripe-best-practices/references/tax.md -o ~/.agents/skills/stripe-best-practices/references/treasury.md https://anymodel.org/en/skills/stripe/stripe-best-practices/references/treasury.md
Claude Code — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE','references/billing.md','references/connect.md','references/payments.md','references/security.md','references/tax.md','references/treasury.md') { $p = Join-Path "$HOME\.claude\skills\stripe-best-practices" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/stripe/stripe-best-practices/$f" -UseBasicParsing -OutFile $p }
Codex, Cursor — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE','references/billing.md','references/connect.md','references/payments.md','references/security.md','references/tax.md','references/treasury.md') { $p = Join-Path "$HOME\.agents\skills\stripe-best-practices" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/stripe/stripe-best-practices/$f" -UseBasicParsing -OutFile $p }

Any other agent: save the file into its skills folder, or give it the link to the file: https://anymodel.org/en/skills/stripe/stripe-best-practices/SKILL.md

SKILL.md

Raw

Latest Stripe API version: 2026-11-18.endive. Always use the latest API version and SDK unless the user specifies otherwise.

Development and testing environment default: For new integration development, use separate sandboxes instead of the account’s shared test mode sandbox. Sandboxes isolate settings and test data from live mode. Use separate sandboxes for local development and CI. When stronger isolation is useful, dedicate sandboxes to development teams or testing scenarios. Use the shared test mode sandbox only for an existing integration that depends on it or when a required feature doesn’t support general sandboxes.

Latest SDK versions:

Language Latest version
Ruby 20.0.0
Python 16.0.0
Node.js 23.0.0
PHP 22.0.0
Java 34.0.0
Go 87.0.0
.NET 53.0.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 using the installation script for your operating system, then open a new terminal 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; don’t 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. Reference paths are relative to this skill’s directory, not to the docs.stripe.com root. If you don’t have the skill files locally, append the path to https://docs.stripe.com/.well-known/skills/stripe-best-practices/. For example, fetch https://docs.stripe.com/.well-known/skills/stripe-best-practices/references/connect.md.

Critical rules

  • Before enabling automatic_tax: { enabled: true } (or calculating tax for a custom PaymentIntent), read the tax reference and follow its setup and verification steps. Without an active registration in the customer’s jurisdiction, Stripe 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.

  • When a PaymentIntent or SetupIntent integration requires an explicit allowlist, use allowed_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:

Connect through AnyModel API

This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.

More from the pack Stripe skills