agentleFS
Sign inStart free
RoentekRoentek/Claude_Code_Boilerplate_Framework/.claude/skills/stripe-best-practices/SKILL.md

stripe-best-practices

Skill4 starsChanged 6 months agoMITView on GitHub

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.

  • Installs packages

24 other projects use a version of this, 13 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use vercel-react-best-practices, frontend-design and 3 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • VercelSkill

    vercel-react-best-practices

    React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.

    Also in 4 projects that use this

  • BlockSkill

    frontend-design

    Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

    Also in 5 projects that use this

  • AnthropicSkill

    pdf

    Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When Claude needs to fill in a PDF form or programmatically process, generate, or analyze PDF documents at scale.

    Also in 3 projects that use this

  • SentrySkill

    skill-creator

    Create new agent skills following the Agent Skills specification. Use when asked to "create a skill", "add a new skill", "write a skill", "make a skill", "build a skill", or scaffold a new skill with SKILL.md. Guides through requirements, writing, registration, and verification.

    Also in 5 projects that use this

  • MicrosoftSkill

    mcp-builder

    Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

5 rules. 0 are common, 2 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 23 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If you don’t have a Stripe account, you can call a CLI command to generate working API keys with no registration required.

    line 31
  2. Very specific:

    If stripe sandbox create is used, don’t use MCP.

    line 33
  3. Very specific:

    If you try to use MCP after running sandbox creation, first make sure stripe sandbox claim is run.

    line 35
  4. Distinctive:

    Read the relevant reference file before answering any integration question or writing code.

    line 53
  5. Distinctive:

    When the user’s request does not clearly fit a single domain above, consult:

    line 69

“Common” is measured: kept by at least 6 in 10 of the 23 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Latest Stripe API version: 2026-07-29.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 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) (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 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:

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free