Stripe Integration Best Practices
Choose the right Stripe APIs and implementation patterns for payments, billing, platforms, tax, and security.
The files explicitly recommend restricted API keys, least privilege, secret storage, rotation, webhook signature verification, OAuth state, stronger 2FA, and confirmation before creating or expiring tax registrations, showing strong awareness of security and external effects. Deducted 6 points because the Stripe CLI test-key instructions lack permission-boundary and risk guidance; data flows, rollback procedures, and all external side effects are not systematically disclosed; and the Connect security guidance is internally inconsistent.
Integration routing, critical rules, and failure traps are fairly concrete, with supporting reference files. Deducted 13 points because the Connect material both mandates Accounts v2 and presents Standard as the safer default while advising against Express/Custom, conflicting with the earlier v2 dashboard guidance; there are no skill-specific tests, input validation rules, or diagnostic failure messages. Static calibration also caps this at 10.
The description names clear scenarios across payments, subscriptions, tax, Connect, Treasury, and security, and the routing table supports semantic triggering. Deducted 6 points because the scope is very broad, non-fit cases, input/output expectations, and trigger exclusions are not defined; Chinese-language support is not addressed; and mainland-China reachability of docs.stripe.com, npm, and Stripe CLI is not discussed.
The skill has front matter, domain-specific reference files, tables of contents, installation guidance, an MIT license, and repository-level synchronization signals. Deducted 7 points because the skill has no own version, changelog, clearly named maintainer, or stable update path; some installation and maintenance details exist only in README context, while troubleshooting, FAQs, and known limitations are incomplete.
The rules can directly guide API selection, dynamic payment methods, tax prerequisites, Connect responsibility configuration, and key security, so the core task is plausibly supported. Deducted 9 points because there are no complete, reproducible outputs or end-to-end examples for representative requests; external documentation access may still require substantial manual verification; and the Connect contradiction can produce incorrect implementations. Static calibration caps this at 7.
The files provide many links to Stripe primary documentation and repository CI and synchronization workflows provide some audit signals. Deducted 6 points because CI mainly covers tool packages rather than this skill's key recommendations, there are no committed skill tests or third-party execution results, and static files cannot independently verify time-sensitive claims about the API version, Metronome, or Accounts v2. Static calibration caps this at 5.
- Resolve the conflict among Accounts v2, Standard, Express, and Custom guidance, and state which configurations apply to each API version.
- Add version sources, update dates, and changelog entries for time-sensitive claims about the latest API version, Metronome, and Accounts v2.
- Add non-fit scenarios, failure handling, end-to-end examples, and alternatives when mainland-China networks cannot reach required Stripe services.
- Before using the Stripe CLI to generate keys, clearly state sandbox scope, permissions, and key lifecycle expectations.
What it does & when to use it
This skill helps developers build, modify, or review Stripe integrations. It covers one-time payments, Checkout, Payment Element, Setup Intents, subscriptions, Connect platforms, Stripe Tax, Treasury financial accounts, and secure key and webhook handling. It routes requests to recommended APIs based on the integration scenario and requires the relevant reference file to be read first. It also specifies the latest Stripe API version and recommends restricted API keys by default.
Routes integration goals to Checkout Sessions, PaymentIntents, Setup Intents, Accounts v2, Billing APIs, Metronome, Stripe Tax, the Registrations API, or v2 Financial Accounts; directs the agent to the relevant payments, connect, billing, tax, treasury, or security reference; checks for an active registration before enabling automatic tax; advises on dynamic payment methods, Checkout session identifiers, API keys, webhooks, OAuth, 2FA, and Connect liability; and documents installing the Stripe CLI with npm and running stripe sandbox create to generate API keys.
- An engineer building a one-time payment flow needs to choose between Checkout Sessions and a custom payment experience.
- A marketplace team needs guidance on setting up Connect Accounts v2 and controller properties.
- A product team implementing subscriptions or usage-based billing needs to select Billing APIs, Checkout Sessions, or Metronome.
- A business collecting sales tax, VAT, or GST needs to validate Stripe Tax, the Registrations API, and active registrations.
- An engineer reviewing a production Stripe integration needs to improve restricted keys, webhooks, OAuth, 2FA, and API key management.
- A team migrating from deprecated Stripe APIs needs to update its implementation for the latest API version.
Pros & cons
- Covers common Stripe integration domains, including payments, billing, Connect, tax, Treasury, and security.
- Provides an explicit API routing table and concrete implementation rules.
- Highlights failure-prone areas such as tax registration, dynamic payment methods, and restricted API keys.
- Released under the MIT license.
- The SKILL.md references several files that were not included in the supplied source, so their full details cannot be verified here.
- No test suite, sample application, or platform compatibility test evidence is provided.
- It provides decision and review guidance rather than a standalone Stripe SDK or complete payment implementation.
- Some workflows depend on Stripe documentation, the Stripe CLI, and network access.
How to install
Run npx skills add https://docs.stripe.com in your project for manual installation. Manually installed skills do not auto-update; run npx skills update -y to update them. The README does not document how to install only this skill from the monorepo.
How to use
Place the skill where your Agent Skills-compatible client can load it, then provide a concrete request such as: “Review my Stripe subscription integration for Checkout Sessions, automatic_tax, webhooks, and restricted API key usage.” Read the relevant reference file before answering an integration question or writing code. The latest Stripe API version is 2026-06-24.dahlia; use the latest API version and SDK unless the user specifies otherwise.
Compared to similar skills
The skill explicitly distinguishes Checkout Sessions from PaymentIntents: Checkout Sessions are recommended for one-time payments; Checkout Sessions with Payment Element are recommended for custom embedded payment forms; and Setup Intents are recommended for saving payment methods. It also says to omit payment_method_types except for Terminal integrations, enabling dynamic payment methods.