mcpField
S
stripe-integration

stripe-integration

github.com/oakoss開発2191 回インストール12 週間前に更新
リポジトリ

stripe-integration について

stripe-integration は、開発者向けの Stripe 決済連携ガイドで、Node.js のサーバー側と React Stripe.js のクライアント側の処理を扱います。一回限りの決済、サブスクリプション、ホスト型チェックアウト、Webhook 検証を説明します。

主な機能

  1. 01Payment Intents とサブスクリプションの作成
  2. 02ホスト型チェックアウトと決済フォームの連携
  3. 03顧客向け請求ポータルの管理
  4. 04Webhook 署名の検証
  5. 05決済確認と認証への対応

活用シーン

  1. 01一回限りの決済フローの構築
  2. 02定期購入と請求管理の実装
  3. 03Webhook による履行処理の起動
  4. 04決済確認やイベント処理の問題調査

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/oakoss/agent-skills --skill stripe-integration

インストール後、Claude Code で/stripe-integrationを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
checkout-and-payments.md
stripe-elements.md
subscriptions.md
webhooks.md

詳細

Stripe Integration

概要

Stripe は、サーバーサイド SDK（Node.js）とクライアントサイドライブラリ（Stripe.js、React Stripe.js）を備えた包括的な決済プラットフォームです。Node.js SDK は、Payment Intents の作成、サブスクリプションの管理、Webhook の検証など、サーバー側の操作を処理します。React Stripe.js ライブラリは、安全なクライアント側での決済情報収集に使える、あらかじめ構築された UI コンポーネント（PaymentElement、Elements プロバイダー）を提供します。

使用する場合： 1 回限りの決済、定期サブスクリプション、従量課金、マーケットプレイスでの支払い、ホスト型チェックアウトページ、カスタム決済フォーム、Webhook によるフルフィルメント。

使用しない場合： 暗号資産による決済（未対応）、Stripe を利用できない地域、決済処理を伴わないシンプルな静的商品販売（ホスト型ストアフロントを使用してください）。

クイックリファレンス

パターンAPIポイント
ホスト型チェックアウトstripe.checkout.sessions.create()Stripe がホストするページで、payment、subscription、setup モードに対応
Payment Intentstripe.paymentIntents.create()サーバー側で実行し、クライアントでの確認に使う client_secret を返します
決済の確認stripe.confirmPayment({ elements, clientSecret })クライアント側で実行し、Elements インスタンスが必要です
サブスクリプションの作成stripe.subscriptions.create()SCA には payment_behavior: 'default_incomplete' を使用します
サブスクリプションの更新stripe.subscriptions.update()proration_behavior を明示的に設定します
サブスクリプションのキャンセルstripe.subscriptions.cancel()未使用期間分をクレジットするには prorate: true を使用します
Customer Portalstripe.billingPortal.sessions.create()セルフサービスの請求管理機能で、有効期限の短い URL を返します
Webhook の検証stripe.webhooks.constructEvent()生の本文、署名ヘッダー、エンドポイントシークレットが必要です
Elements プロバイダー<Elements stripe={stripePromise} options={options}>決済コンポーネントをラップし、clientSecret または mode を渡します
PaymentElement<PaymentElement />対応するすべての決済方法を自動的に表示します
取得と展開stripe.checkout.sessions.retrieve(id, { expand })ネストされたオブジェクトを展開して API 呼び出しを減らします
検索stripe.paymentIntents.search({ query })絞り込みには Stripe Query Language を使用します

よくある間違い

間違い正しいパターン
検証前にWebhookの本文をJSONとして解析するexpress.raw({ type: 'application/json' }) を使って、生の本文を constructEvent に渡します
支払い方法の種類をハードコードするautomatic_payment_methods を使うか、通貨と地域に基づいてCheckoutに選択させます
クライアント側でPaymentIntentを作成するサーバー側で作成し、client_secret のみをクライアントに渡します
確認前に elements.submit() を待機しないまず elements.submit() を呼び出して検証を実行し、その後 confirmPayment を呼び出します
confirmPayment に return_url を指定しないリダイレクトベースの支払い方法では、必ず return_url を指定します
本番環境でテストキーを使うキーを環境変数に保存し、STRIPE_SECRET_KEY のプレフィックス（sk_live_ と sk_test_）を検証します
requires_action のステータスを処理しない確認後にPaymentIntentのステータスを確認し、3Dセキュアなどの認証を処理します
設定せずにCustomer Portalのセッションを作成するまずDashboardでポータル設定を保存します。保存しない場合、APIはエラーを返します
関連オブジェクトを展開しないexpand パラメーターを使って、latest_invoice.payment_intent などのネストされたオブジェクトを含めます
Webhookの冪等性を無視するevent.id を使って重複を除外します。Webhookイベントは複数回配信されることがあります

委任

  • 支払いフローのアーキテクチャ：Explore エージェントを使って、統合パターンを調査します
  • Webhookのデバッグ：Task エージェントを使って、イベントをエンドツーエンドで追跡します
  • コードレビュー：支払いハンドラーのセキュリティレビューを code-reviewer エージェントに委任します

参考資料

コメント

Markdown 対応