SkillRepo
Sign InSign Up
Catalog
stripe/stripe-best-practices

stripe

stripe-best-practices

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.

NewUpdated Sep 11, 2026

Latest Stripe API version: 2026-08-26.dahlia. 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 19.6.0
Python 15.6.0
Node.js 22.6.0
PHP 21.3.0
Java 33.4.0
Go 86.4.0
.NET 52.4.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 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 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.

  • 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:

Files7
7 files · 58.3 KB

Select a file to preview

Overall Score

88/100

Grade

A

Excellent

Grades are signals, not a certification. Always review a skill yourself before use.

Safety

88

Quality

90

Clarity

87

Completeness

84

Summary

This skill guides Stripe integration decisions across development environment planning, API selection, billing, tax compliance, Connect platform setup, security best practices, and migration paths. It provides routing tables, critical rules, and detailed reference material for choosing the right Stripe APIs and configurations based on use case (payments, subscriptions, marketplaces, tax, etc.).

Detected Capabilities

API documentation referenceConfiguration guidanceSecurity best practices documentationTax compliance guidanceConnect platform architecture guidance

Trigger Keywords

Phrases that agents use to match this skill to user intent.

stripe integration planningchoose payment APIstripe connect marketplacestripe tax setupapi key securitystripe billing subscriptionsmigrate from charges apiwebhook security

Risk Signals

INFO

Guidance on API key management and restricted API keys (RAK) recommends storing keys in secrets vaults and warns against hardcoding

references/security.md: API keys section
INFO

Webhook signature verification is recommended as mandatory security practice

references/security.md: Webhook security section
INFO

Documentation provides OAuth state parameter guidance for CSRF protection

references/security.md: OAuth and CSRF protection section
INFO

Guidance addresses tax calculation without active registrations—the most common Stripe Tax mistake

references/tax.md: When tax applies section

Referenced Domains

External domains referenced in skill content, detected by static analysis.

*.link.com*.stripe.comdashboard.stripe.comdocs.stripe.comstripe.comsupport.stripe.comvercel.com

Use Cases

  • Plan Stripe integration architecture for payments or subscriptions
  • Choose between Checkout Sessions, PaymentIntents, and Connect APIs
  • Set up tax compliance with Stripe Tax and registrations
  • Build marketplace or SaaS platform with Connect v2
  • Implement security best practices for API keys, webhooks, and OAuth
  • Migrate from deprecated Stripe APIs (Charges, Sources, Card Element)
  • Configure billing and usage-based subscription systems
  • Set up financial accounts and Treasury integrations

Quality Notes

  • Comprehensive routing table maps business models and use cases to specific APIs and configurations
  • Critical rules are clearly marked and separated from general guidance; easy for an agent to identify must-follow constraints
  • Extensive reference files cover five major domains (payments, billing, tax, security, Connect) with detailed guidance and common pitfalls
  • Tax reference is exceptionally thorough: covers diagnosis of zero-tax scenarios, per-jurisdiction setup, Connect liability models, and registration safety
  • Security reference addresses modern best practices (RAKs, ephemeral keys, SSO/SAML, passkeys over SMS 2FA)
  • Deprecated API migration paths are documented with links
  • Documentation includes practical tables for business-model-to-config mapping and tax/billing API selection logic
  • SDKs and latest API versions are documented at the top for quick reference
  • Addresses common mistakes and anti-patterns explicitly (e.g., hardcoding payment_method_types, using v1 Connect types, enabling automatic_tax without registrations)
  • Well-structured with table of contents, clear section hierarchy, and appropriate use of bold/italics for emphasis
Model: claude-haiku-4-5-20251001Analyzed: Sep 11, 2026

Reviews

Add this skill to your library to leave a review.

No reviews yet

Be the first to share your experience.

Version History

  1. v3.1

    Content updated

    +2 −0 lines in SKILL.md · references/payments.md updated

    2026-09-11

    LATEST
  2. v3.0

    Contract changed: description

    ✦ AIAdds guidance on development environment strategy: prefer separate sandboxes over shared test mode for new Stripe integrations.

    triggering2026-09-10

    View This Version
  3. v2.0

    Contract changed: description

    ✦ AIUpdates API version to 2026-08-26, adds SDK version table, restructures MCP setup and sandbox guidance, expands tax handling and webhooks as required, adds integration_identifier tracking, emphasizes…

    triggering2026-09-09

    View This Version
  4. v1.1

    Content updated

    ✦ AIUpdates API version to 2026-06-24.dahlia, adds Stripe MCP server requirement, introduces Restricted API Key (RAK) best practice, adds usage-based billing and tax compliance routing options, expands…

    2026-06-28

    View This Version
  5. v1.0

    2026-05-02

    View This VersionInitial version

Use stripe/stripe-best-practices in your dev environment

Start a Developer trial

Command Palette

Search for a command to run...