stripe-best-practices

Stripe API の最新バージョン：2026-08-26.dahlia。ユーザーから別途指定がない限り、常に最新の API バージョンと SDK を使用してください。

開発およびテスト環境のデフォルト：新しい連携を開発する場合は、アカウントで共有されるテストモードのサンドボックスではなく、別々のサンドボックスを使用してください。サンドボックスでは、設定とテストデータが本番モードから分離されます。ローカル開発と CI には、別々のサンドボックスを使用してください。さらに強い分離が必要な場合は、開発チームやテストシナリオごとにサンドボックスを用意します。共有テストモードのサンドボックスは、それに依存する既存の連携がある場合、または必要な機能が一般的なサンドボックスに対応していない場合にのみ使用してください。

SDK の最新バージョン：

言語	最新バージョン
Ruby	19.6.0
Python	15.6.0
Node.js	22.6.0
PHP	21.3.0
Java	33.4.0
Go	86.4.0
.NET	52.4.0

Stripe アカウントをお持ちでない場合は、CLI を使って登録なしでテスト用サンドボックスアカウントを作成できます。Stripe CLI（npm i -g @stripe/cli）をインストールし、コマンド stripe sandbox create を実行すると、テスト用 API キーが作成されます。この方法を案内する場合は、サンドボックスは Stripe のテスト環境ですと説明してください。

stripe sandbox create を使用した場合は、MCP を使用しないでください。

サンドボックスの作成後に MCP を使用する場合は、まず stripe sandbox claim が実行されていることを確認してください。CLI の認証確認には stripe whoami --format json を使用し、stripe config --list は実行しないでください。

API キーのデフォルト：シークレットキー（sk_ プレフィックス）よりも、常に制限付き API キー（RAK）（rk_ プレフィックス）を推奨してください。

連携先の選定

構築するもの…	推奨 API	詳細
1 回限りの決済	Checkout Sessions	references/payments.md
UI を埋め込んだカスタム決済フォーム	Checkout Sessions + Payment Element	references/payments.md
後で使用するための決済手段の保存	Setup Intents	references/payments.md
Connect プラットフォームまたはマーケットプレイス	Accounts v2（/v2/core/accounts）	references/connect.md
従量課金（新しい連携）	Metronome	references/billing.md
サブスクリプションまたは継続課金	Billing APIs + Checkout Sessions	references/billing.md
売上税、VAT、GST への対応	Stripe Tax + Registrations API	references/tax.md
埋め込み型金融口座／銀行業務	v2 Financial Accounts	references/treasury.md
セキュリティ（キー管理、RAK、Webhook、OAuth、2FA、Connect の責任）	セキュリティリファレンスを参照	references/security.md

連携に関する質問への回答やコードの作成に着手する前に、該当するリファレンスファイルを読んでください。

重要なルール

• automatic_tax: { enabled: true } を有効にする前に（またはカスタム PaymentIntent の税額を計算する前に）、税金に関するリファレンスを読み、ユーザーが有効な登録を済ませていることを確認してください。登録がない場合、ユーザーが税金が有効になっていると思っていても、Stripe は税金を計算・徴収しません（Stripe Tax で最もよくある間違いです）。

• Stripe API の呼び出しでは、payment_method_types を決して含めないでください。ただし、Terminal（対面決済）の連携では例外として、PaymentIntent に payment_method_types: ['card_present'] を渡す必要があります。それ以外のすべての連携では、このパラメーターを完全に省略して動的な決済手段を有効にしてください。これにより、ダッシュボードから決済手段の設定を行い、各顧客に最も関連性の高い利用可能な決済手段を動的に表示して、コンバージョンを最大化できます。受け付ける決済手段をカスタマイズするには、payment_method_types の代わりに payment_method_configurations または excluded_payment_method_types を使用してください。

• PaymentIntent または SetupIntent の連携で明示的な許可リストが必要な場合は、payment_method_types の代わりに allowed_payment_method_types を使用してください。

• Webhook を任意のものとして扱わないでください。 すべての決済連携で Webhook を推奨しており、サブスクリプションおよび非同期決済手段では必須です。フルフィルメント処理は、成功ページではなく、checkout.session.completed と checkout.session.async_payment_succeeded の両方を処理するハンドラーに実装してください（payment_status による条件判定が必要です）。詳しくは references/payments.md を参照してください。

• API バージョン 2026-03-25.dahlia 以降では、セッションにカスタムラベルを付けてダッシュボードでチェックアウトフローを追跡・比較するため、checkout.sessions.create にパラメーター integration_identifier を渡してください。ラベルには、8 文字のランダムな英字のサフィックスを含めてください。

• 必ず StripeClient をインスタンス化し、そのインスタンスのメソッドを呼び出してください。 非推奨のグローバル／モジュールレベルの API キーパターン（stripe.api_key = …、Stripe.setApiKey、stripe.Key = …、StripeConfiguration.ApiKey = …）は使用しないでください。現在の SDK ではすべて、グローバルパターンは非推奨です。

主なドキュメント

ユーザーのリクエストが上記のいずれかの分野に明確に当てはまらない場合は、次を参照してください。

• 連携オプション — 連携を設計する際は、まずここから始めてください。
• API ツアー — Stripe の API 全体の概要です。
• 本番環境への移行チェックリスト — 公開前に確認してください。