stripe-best-practices

Stripe Best Practices — скилл для проектирования, изменения и проверки интеграций Stripe. Он охватывает выбор API для разовых платежей и подписок, кастомные формы оплаты, Connect-платформы и маркетплейсы, налоги, финансовые счета, миграцию с устаревших API, ключи, webhooks и OAuth. Ценность карточки не в одном универсальном шаблоне: сначала нужно определить тип продукта и затем открыть соответствующий справочный материал исходного репозитория. В источнике отдельно перечислены материалы по payments, Connect, billing, tax, treasury и security. Для разового платежа базовым маршрутом назван Checkout Sessions. Если нужен встроенный пользовательский интерфейс, рекомендуется сочетание Checkout Sessions и Payment Element. Сохранение платёжного метода для будущего использования относится к Setup Intents. Для платформ и маркетплейсов источник указывает Accounts v2 с маршрутом /v2/core/accounts. Подписки и регулярные списания требуют Billing APIs вместе с Checkout Sessions. Новый usage-based billing вынесен в Metronome. Для sales tax, VAT и GST связка строится вокруг Stripe Tax и Registrations API, а встроенные финансовые счета относятся к v2 Financial Accounts. Это не отменяет проверки конкретного сценария: таблица помогает выбрать направление, но не подменяет чтение reference-файла. У скилла есть несколько защитных правил, которые нужно учитывать до записи кода. Перед включением automatic_tax или ручным расчётом налога через PaymentIntent сначала проверяется tax reference и активная регистрация; без регистрации Stripe не рассчитывает и не собирает налог так, как может ожидать владелец интеграции. Параметр payment_method_types не следует добавлять в обычные вызовы: исключение в источнике сделано для Terminal, где PaymentIntent получает card_present. Для API-версий от 2026-03-25.dahlia при создании Checkout Session предусмотрен integration_identifier с суффиксом из восьми случайных букв для отслеживания потоков в Dashboard. С точки зрения SDK скилл требует создавать экземпляр StripeClient и вызывать методы на нём. Глобальный стиль с записью API-ключа в модульную переменную помечен как устаревший. Для ключей рекомендуется ограниченный restricted API key с префиксом rk_, а секреты нельзя встраивать в клиентский код, коммитить или выводить в логи. Webhook, OAuth, Connect-liability и двухфакторная защита относятся к отдельному security reference и должны проверяться до запуска. Карточка полезна при выборе интеграционного маршрута и ревью уже написанного платежного кода. Она не заменяет юридическую проверку налоговых обязанностей, настройку регистрации в нужной юрисдикции, проверку актуальной версии SDK или тестирование webhook-повторений. Зафиксированная в исходном SKILL.md версия Stripe API — 2026-07-29.dahlia; перед production-релизом её и версии SDK нужно сверить с официальной документацией Stripe, потому что такие значения меняются. Без чтения соответствующего reference и проверки состояния аккаунта нельзя считать рекомендацию готовой к боевому включению.