Backend · Skill

Apply Stripe best practices

apply-stripe-best-practices

Reviews or plans a Stripe integration against Stripe's own guidance - pick the right API (hosted pages, Payment Element, Setup Intents, Connect, Tax), use restricted keys and sandboxes, and make webhook handling signed and idempotent. Use when choosing which Stripe API to use, reviewing existing Stripe code, or hardening a Stripe account before launch.

Works with: Any AI Not yet model-tested; testing Jan 2027

View raw SKILL.mdInstall

Paste it into ChatGPT, Claude, Gemini or any AI chat, then tell it about your project. How it works

Install in Claude Code, Cursor or Codex (optional)

Only for AI coding tools that read skill folders. Run one line in a terminal, in your project folder. It downloads this skill's text files from TheSkillVault and nothing else; you can read them first with “View raw SKILL.md”.

Claude Code (all your projects)

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/apply-stripe-best-practices/raw' -o ~/'.claude/skills/apply-stripe-best-practices/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/apply-stripe-best-practices/files/LICENSE.txt' -o ~/'.claude/skills/apply-stripe-best-practices/LICENSE.txt'

Cursor (this project)

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/apply-stripe-best-practices/raw' -o '.cursor/skills/apply-stripe-best-practices/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/apply-stripe-best-practices/files/LICENSE.txt' -o '.cursor/skills/apply-stripe-best-practices/LICENSE.txt'

Codex and other Agent Skills tools (this project)

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/apply-stripe-best-practices/raw' -o '.agents/skills/apply-stripe-best-practices/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/apply-stripe-best-practices/files/LICENSE.txt' -o '.agents/skills/apply-stripe-best-practices/LICENSE.txt'

Or connect the whole library over MCP

Add TheSkillVault to Cursor or add this to your app's MCP settings (read-only; help):

{
  "mcpServers": {
    "theskillvault": {
      "url": "https://theskillvault.ai/mcp"
    }
  }
}

A checklist for choosing the right Stripe building block and checking an existing integration. It is a review skill. For building a first checkout page, use the add-stripe-checkout skill instead.

When to use

  • You are about to add payments and are not sure which Stripe API fits.
  • You want a second opinion on Stripe code before going live.
  • You are adding subscriptions, a marketplace, saved cards or sales tax.

When not to use

  • You only need a simple hosted checkout working today. Use add-stripe-checkout.

Steps

  1. Write down what you are selling and how people pay: one-off, saved card, subscription, usage-based, marketplace payouts.
  2. Pick the API from the table below. Prefer the hosted or embedded Stripe UI over a hand-built card form.
  3. Check the keys. The browser only ever sees the publishable key. Server code uses a restricted key (rk_) with only the permissions it needs, kept in an environment variable.
  4. Check the environment. Build in a Stripe sandbox, with a separate one for CI, never in live mode.
  5. Check webhooks. Fulfil orders in a webhook handler that verifies the signature, never on the success page.
  6. Check the client setup. Create one Stripe client instance with the key, rather than setting a global key.
  7. Check payment methods. Leave the payment method list to the Dashboard so Stripe can show the best local options.
  8. If tax is on, confirm the account has an active tax registration for each place you collect.
  9. Run Stripe's go-live checklist, then do one real low-value payment and refund it.
| You are building | Start with |
| --- | --- |
| One-off payments | Checkout Sessions |
| Custom-looking checkout on your page | Checkout Sessions with the Payment Element |
| Save a card to charge later | Setup Intents |
| Subscriptions | Billing with Checkout Sessions |
| Marketplace or platform payouts | Connect |
| Sales tax, VAT or GST | Stripe Tax plus registrations |

Gotchas

  • A secret key in front-end code, a repo or a screenshot is a leak. Roll it in the Dashboard at once.
  • Hard-coding a list of payment method types hides methods your customers prefer. Configure them in the Dashboard instead.
  • The success page can be closed or faked. Only the verified webhook event proves payment.
  • Delayed methods (bank debits) succeed later. Handle the async success event too, not just "completed".
  • Turning on automatic tax without a registration collects nothing, silently.
  • Stripe's API changes. Check the current API version in Stripe's docs before copying old snippets.

Portability

Works with any backend language Stripe has an SDK for. If you use a framework like Next.js, Rails or FastAPI, the same checks apply; only the file names change.

Example prompt

"Review my Stripe code before launch. Am I using the right API for subscriptions and are my keys and webhooks safe?"

Done when

  • Each payment flow maps to one row of the table.
  • No secret key is in client code or git; server code uses a restricted key from the environment.
  • Fulfilment runs only from a signature-verified webhook.
  • A test payment and refund work end to end in a sandbox.

---

Adapted from "stripe-best-practices" in stripe/ai (MIT, Copyright (c) 2024–2025 Stripe). See LICENSE.txt.

Bundled files

Licence

Adapted from Stripe (stripe/ai, stripe-best-practices) (Copyright (c) 2024–2025 Stripe), MIT License. Adapted by TheSkillVault: rewritten as a beginner review checklist with a decision table, steps, gotchas and done-when; dropped SDK version tables, CLI sandbox commands and the reference-file links.

Licence: MIT License. Attribution when you reuse it: Based on work by Stripe (stripe/ai, stripe-best-practices) (Copyright (c) 2024–2025 Stripe, MIT License), https://github.com/stripe/ai/tree/1e24cf59cb0dd78df298afc3b7d372e5a5055ece/skills/stripe-best-practices; adapted by TheSkillVault, https://theskillvault.ai