Index of every page on this site: llms.txt
All skills
stripe avatar

/stripe-best-practices

@119bc4a official
by stripestripe/ai2.1k stars
384
Run it yourself

Guides Stripe integration decisions across development and test environment planning (separate sandboxes vs the shared test mode sandbox), 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, API key permissions, webhooks, OAuth). Use when planning, building, modifying, testing, or reviewing any Stripe integration, including choosing a development environment, 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.

Use this Skill: https://skilld.dev/gh/stripe/ai/stripe-best-practices

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈229 tokens for metadata: the name and description. ≈1.4k when used: this file. ≈17k more on demand in 6 files.

Description uses 11.5% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈917 characters, or 11.5%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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:

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alertstoday5 checks · Risk SAFE
  • Gen Agent Trust Hubtoday

    This skill provides detailed architectural guidance and security best practices for integrating Stripe. It includes recommendations for API selection, development environments, and secure key management. All external references are to official Stripe documentation, which is the intended behavior of the skill.

  • Socket1d

    No alerts

  • Snyktoday

    Risk: LOW · No issues

  • Runlayer8mo

    1/1 file flagged

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 119bc4a. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated yesterday
  • Security
  • stripe
  • payments
  • billing
  • connect
  • webhooks
  • api-design
  • subscriptions
  • marketplace

README badge

README badge for stripe/ai/stripe-best-practices

Guides decisions on Stripe API selection, Connect platform setup, billing and subscriptions, Treasury financial accounts, and security best practices including restricted keys and webhooks. Use when building or reviewing any Stripe integration — payments, marketplaces, subscriptions, or connected accounts.

Generated from the current SKILL.md.

Should I use Checkout Sessions or PaymentIntents?
Use Checkout Sessions for one-time payments and custom forms with Payment Element. PaymentIntents are lower-level and require more manual implementation; use them only when Checkout Sessions cannot meet your requirements.
What API version should I target?
Always use the latest Stripe API version (2026-05-27.dahlia) unless the user explicitly requests otherwise.
Should I use restricted API keys or secret keys?
Always use restricted API keys (rk_ prefix) over secret keys (sk_ prefix) to limit scope and improve security.
Does this skill cover Connect marketplaces and platform setup?
Yes. It includes guidance on Accounts v2, controller properties, and platform liability. Consult the Connect reference before building marketplace features.
What should I do before writing payment or billing code?
Install the Stripe MCP server and call the stripe_implementation_planner tool with your business description to get a tailored integration guide. If MCP is unavailable, use the integration routing table in the skill.

Generated from the current SKILL.md. These answers refresh after source changes.