stripe-best-practices

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

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

最新のSDKバージョン：

言語	最新バージョン
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

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 を使用してください。

• ウェブフックを任意のものとして扱わないでください。すべての決済連携でウェブフックを推奨しており、サブスクリプションと非同期決済手段では必須です。フルフィルメント処理は成功ページではなく、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 の概要です。
• 本番環境への移行チェックリスト — リリース前に確認してください。