Лучшие практики интеграции Stripe

Делает интеграцию со Stripe на актуальных API: Checkout Sessions, Accounts v2, Billing, Stripe Tax, обязательные вебхуки, без payment_method_types, с ограниченными ключами. Для случаев, когда агент пишет, меняет или проверяет код со Stripe.

РазработкаПак: Скиллы Stripe79 строкstripe-best-practices
Автор
Источник
stripe/ai/skills/stripe-best-practices @ 119bc4a
Лицензия
MIT · Copyright (c) 2024–2025 Stripe

Об этом скилле

Что делает

Скилл Stripe с лучшими практиками направляет решения агента по интеграции Stripe к тем API, которые Stripe рекомендует сейчас. В SKILL.md зафиксирована последняя версия API (в нашей копии 2026-11-18.endive) и версии SDK для семи языков. Каждый тип задачи SKILL.md отправляет в справочник, который агент обязан прочитать до ответа. Это payments.md (Checkout Sessions, Payment Element, выдача заказа, устаревшие API), billing.md (подписки, Metronome для оплаты по потреблению), connect.md (Accounts v2), tax.md (Stripe Tax), treasury.md (v2 Financial Accounts) и security.md.

Несколько правил повторяются в разных файлах. Не передавать payment_method_types — исключение только card_present для Terminal. Вебхуки обязательны: заказ выдаётся по checkout.session.completed и checkout.session.async_payment_succeeded с проверкой payment_status, а не на странице успешной оплаты. automatic_tax без активной регистрации не собирает налог и не выдаёт ошибку. Одно правило есть только в SKILL.md: работать через экземпляр StripeClient, а не через глобальный ключ. Справочник по безопасности предпочитает ограниченные ключи (rk_) секретным (sk_). Ещё он добавляет хранилище секретов для каждого облака, регулярное выражение для поиска боевых ключей в коде, pre-commit хук, переход на ограниченные ключи в шесть шагов, ограничения по IP, параметр state в OAuth и 2FA.

Новую работу скилл ведёт в отдельных песочницах, а не в общем тестовом режиме; stripe sandbox create создаёт песочницу без аккаунта. Если подключены Stripe CLI или MCP, агент сам проверяет налог по taxability_reason, а в боевом режиме делает предпросмотр счёта вместо платных расчётов налога.

Когда включать и когда не надо

Всякий раз, когда агент пишет, меняет или проверяет код со Stripe.

Номера версий взяты из нашей зафиксированной копии — сверяйте их с актуальной документацией Stripe. Оплату по потреблению скилл передаёт скиллу metronome, которого в нашем каталоге нет; его адрес на docs.stripe.com указан в тексте.

Как поставить и вызвать

Команда установки ниже скачивает SKILL.md, шесть справочников и лицензию. В репозитории Stripe те же скиллы упакованы для нескольких агентов в providers/, наша копия взята из skills/.

  • Claude Code: /stripe-best-practices или попросить скилл по имени.
  • Codex: $stripe-best-practices.
  • Cursor: наберите / в чате Agent и выберите stripe-best-practices.

Пример: /stripe-best-practices Проверь оформление подписки в src/billing: вебхуки, налоги и то, как хранятся ключи.

Чем отличается от похожих

План внедрения Stripe из того же набора подбирает продукты для нового подключения через stripe tools plan, а отладку, обновления и правки кода отправляет сюда. Приложения Stripe Apps — про приложения внутри Dashboard Stripe. Других скиллов про платежи в нашем каталоге нет. Аудит секретов и конфигурации ищет зашитые секреты в любом репозитории, а правила безопасности здесь — собственные правила Stripe, вплоть до префиксов ключей и подписи вебхуков.

Установка

Выполните одну команду — она сохранит SKILL.md и файлы, которые он использует, в папку скиллов агента. Claude Code и Codex подхватывают новый скилл без перезапуска; если скилл не появился, перезапустите агента.

Скилл написан на английском — агент поймёт его и ответит вам по-русски.

Claude Code — macOS, Linux
curl -fsSL --create-dirs -o ~/.claude/skills/stripe-best-practices/SKILL.md https://anymodel.org/en/skills/stripe/stripe-best-practices/SKILL.md -o ~/.claude/skills/stripe-best-practices/LICENSE https://anymodel.org/en/skills/stripe/stripe-best-practices/LICENSE -o ~/.claude/skills/stripe-best-practices/references/billing.md https://anymodel.org/en/skills/stripe/stripe-best-practices/references/billing.md -o ~/.claude/skills/stripe-best-practices/references/connect.md https://anymodel.org/en/skills/stripe/stripe-best-practices/references/connect.md -o ~/.claude/skills/stripe-best-practices/references/payments.md https://anymodel.org/en/skills/stripe/stripe-best-practices/references/payments.md -o ~/.claude/skills/stripe-best-practices/references/security.md https://anymodel.org/en/skills/stripe/stripe-best-practices/references/security.md -o ~/.claude/skills/stripe-best-practices/references/tax.md https://anymodel.org/en/skills/stripe/stripe-best-practices/references/tax.md -o ~/.claude/skills/stripe-best-practices/references/treasury.md https://anymodel.org/en/skills/stripe/stripe-best-practices/references/treasury.md
Codex, Cursor — macOS, Linux
curl -fsSL --create-dirs -o ~/.agents/skills/stripe-best-practices/SKILL.md https://anymodel.org/en/skills/stripe/stripe-best-practices/SKILL.md -o ~/.agents/skills/stripe-best-practices/LICENSE https://anymodel.org/en/skills/stripe/stripe-best-practices/LICENSE -o ~/.agents/skills/stripe-best-practices/references/billing.md https://anymodel.org/en/skills/stripe/stripe-best-practices/references/billing.md -o ~/.agents/skills/stripe-best-practices/references/connect.md https://anymodel.org/en/skills/stripe/stripe-best-practices/references/connect.md -o ~/.agents/skills/stripe-best-practices/references/payments.md https://anymodel.org/en/skills/stripe/stripe-best-practices/references/payments.md -o ~/.agents/skills/stripe-best-practices/references/security.md https://anymodel.org/en/skills/stripe/stripe-best-practices/references/security.md -o ~/.agents/skills/stripe-best-practices/references/tax.md https://anymodel.org/en/skills/stripe/stripe-best-practices/references/tax.md -o ~/.agents/skills/stripe-best-practices/references/treasury.md https://anymodel.org/en/skills/stripe/stripe-best-practices/references/treasury.md
Claude Code — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE','references/billing.md','references/connect.md','references/payments.md','references/security.md','references/tax.md','references/treasury.md') { $p = Join-Path "$HOME\.claude\skills\stripe-best-practices" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/stripe/stripe-best-practices/$f" -UseBasicParsing -OutFile $p }
Codex, Cursor — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE','references/billing.md','references/connect.md','references/payments.md','references/security.md','references/tax.md','references/treasury.md') { $p = Join-Path "$HOME\.agents\skills\stripe-best-practices" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/stripe/stripe-best-practices/$f" -UseBasicParsing -OutFile $p }

Другой агент: сохраните файл в его папку скиллов или дайте ему ссылку на файл: https://anymodel.org/en/skills/stripe/stripe-best-practices/SKILL.md

SKILL.md

Исходник

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:

Подключить через AnyModel API

Скилл работает на той модели, которую использует агент. Подключите Claude Code, Codex или Cursor к AnyModel и запускайте его на Claude, GPT, Gemini и других моделях по одному ключу — оплата за токены, без подписки.

Ещё из пака Скиллы Stripe