stripe-best-practices

Stripe を組み込む・直す・見直すときに、どの API を選ぶかを決めさせるスキルです。Stripe 自身が公開しており、開発用の環境の選び方から、決済、定期課金、Connect（複数の売り手を扱う基盤）、税、Treasury（組み込みの金融口座）、鍵の扱いまでを受け持ちます。

本文は短く、作るものごとに読む手引きを振り分ける表と、破ってはいけない決まりでできています。手引きを読んでから答える・コードを書く、という順番が指示されています。

作るものごとの振り分けの表

9 行

破ってはいけない決まり

6 項目

同梱の手引き（2026-10-23 時点）

6 件

最新の SDK の版を載せた表

7 言語

作るものごとの振り分け

開発用の環境は「分けた sandbox」

新しい組み込みの開発では、アカウントに 1 つある共有の試験モードではなく、別々の sandbox を使うのが既定です。sandbox は設定と試験のデータを本番から切り離し、手元の開発と CI でも分けるよう書かれています。

アカウントが無ければ、Stripe CLI の stripe sandbox create で、登録なしに試験用の鍵を作れます。この道を使ったら MCP は使わず、使うなら先に stripe sandbox claim を流す決まりです。

版は最新を使う

本文の冒頭には、最新の API の版（2026-09-30.endive）と、Ruby・Python・Node.js・PHP・Java・Go・.NET の最新の SDK の版が書かれています（2026-10-23 時点の原本の値）。利用者が指定しない限り、最新の API の版と SDK を使うよう指示しています。

API の版を上げる作業そのもの

既存の組み込みの版を上げるなら、同じ公開元の upgrade-stripe のほうが手順が細かくそろっています。このスキルは「どれを選ぶか」の判断が中心です。

データベースや外部のサービスを用意したいとき

Stripe の CLI で外部のサービスを用意して鍵を受け取りたいなら、stripe-projects の受け持ちです。

税の義務を判断してほしいとき

どこで登録すべきか、法的な義務があるかは答えない、と税の手引きに明記されています。手引きは「助言でなく案内」とし、税理士などの専門家に相談するよう勧める立場です。

本番の鍵を扱う決まり

鍵はプラットフォームの秘密の保管庫に置き、ソースやコミットする環境変数のファイルには置きません。AWS・Google Cloud・Azure・Vercel ごとの置き場所の案内もあります。

ほかに、本番・ステージング・QA で鍵を分ける、担当者が辞めたら鍵を入れ替える、鍵をログやエラーの文に出さない、コミット前のフックで sk_ や rk_ を止める、が並びます。スマートフォンのアプリやブラウザのコードには本番の鍵を入れず、使い捨ての鍵（ephemeral keys）か自前のサーバーを経由させます。

鍵が漏れたら、まず入れ替える

漏れた・漏れたかもしれないときは、使われたか分からなくても、すぐに API の鍵のページで入れ替えるか消すよう書かれています。次に Workbench の要求の記録で見覚えのない動きを探し、あれば Stripe のサポートに連絡します。

Webhook は省けない

支払いの組み込みには必ず Webhook を勧め、定期課金と後から結果が届く支払い方法では必須だとしています。「あとで」「任意」と書くことも禁じています。

発送や権限の付与は、成功の画面ではなく出来事の受け口で行います。checkout.session.completed と checkout.session.async_payment_succeeded の両方を受け、payment_status が unpaid でないときだけ処理します。処理の前には必ず署名を確かめます。

支払い方法を固定しない

payment_method_types は、どの呼び出しにも渡さない決まりです。渡さなければ Stripe が通貨や地域などから合う支払い方法を出し、管理画面から切り替えられます。

例外は対面の支払い（Terminal）だけで、['card_present'] を渡し、カナダでは interac_present も足します。絞りたいときは payment_method_configurations、excluded_payment_method_types、許可の一覧が要るなら allowed_payment_method_types を使います。

税は「有効にした」だけでは取られない

automatic_tax を有効にしても、その地域で有効な税の登録が無ければ、エラーも出ずに税はまったく計算も徴収もされません。本文はこれを Stripe Tax でいちばん多い間違いとし、有効にする前に登録を確かめるよう決めています。

税の登録を Stripe に足しても、税務当局に登録したことにはなりません。登録の失効は、効力が出たあとは取り消せず（消す操作も一時停止も無い）、登録や失効は自動で行わず利用者の確認を取る決まりです。

Connect の費用と責任

Express と Custom の接続アカウントでは、不正と異議申し立ての金銭的な責任を基盤の運営者が負う、と鍵の手引きに書かれています。Connect の手引きは、基盤の手数料が低い（およそ 4% 未満）なら、Stripe の手数料の見込みを application_fee_amount に含めて利幅を守るよう勧め、料金は stripe.com/pricing を見るよう案内しています。

そのほかの決まり

• StripeClient を作ってそのメソッドを呼ぶ。グローバルに鍵を置く書き方（stripe.api_key = … など）は使わない
• 2026-03-25.dahlia 以降では、checkout.sessions.create に integration_identifier を渡す。末尾に 8 文字のランダムな英字を付ける
• Charges API は勧めない。Sources API・Tokens API・Card Element も代わりのものへ移す
• 新しい使った分だけの課金は、Billing Meters ではなく Metronome を勧める。既存の定期課金を、使った分の課金を足すために解約しない

本文に書かれている操作

本文には Stripe CLI の導入（npm i -g @stripe/cli）と stripe sandbox create、stripe whoami --format json が出てきます。CLI の認証の確認に stripe config --list を流さない、とも書かれています。

Checkout Sessions と PaymentIntents のどちらを使いますか

その場の支払いは Checkout Sessions が勧められています。1 回きりの支払いと定期課金の両方に使え、割引や配送も扱います。PaymentIntents は、利用者がいない場での請求や、支払いの状態を自分で組み立てたいときに使います。

試すのに本番のアカウントは要りますか

要りません。Stripe CLI の stripe sandbox create で、登録なしに試験用の環境と鍵を作れます。本文は、これを勧めるときに「sandbox は Stripe の試験用の環境だ」と説明するよう求めています。

定期課金で受けるべき出来事は何ですか

customer.subscription.*、invoice.paid、invoice.payment_failed の受け口が無いうちは完成と呼ばない、と定期課金の手引きに書かれています。本番では、異議申し立て・返金・不正の早期警告（charge.dispute.created、charge.refunded、radar.early_fraud_warning.created）も受けます。

定期課金の質問に、税の話まで出てくるのはなぜですか

定期課金の手引きが、設定や定期課金の質問に答えるときは必ず Stripe Tax の短い注意を添えるよう決めているためです。利用者に聞かれる前に、米国や EU の顧客に請求するなら Stripe Tax を考える必要がある、と伝える形です。