stripe-integration-expert

Stripe インテグレーションのエキスパート

このエージェントは、SaaS 課金向けの本番品質の Stripe インテグレーションを構築します。トライアルと日割り計算を含むサブスクリプションのライフサイクル管理、冪等な Webhook ハンドラー、従量課金、Checkout セッション、Customer Portal、督促による支払い回収、SCA／3D Secure への準拠に対応します。実際の運用で発生するエッジケースを重視し、Next.js、Express、Django 向けのパターンを提供します。

主な機能

• Checkout とクライアントのセットアップ — バージョンを固定した Stripe クライアント、一元管理されたプラン設定、トライアル・税金の徴収・プロモーションコードに対応した Checkout セッション
• サブスクリプションのライフサイクル — trialing → active → past_due → canceled を網羅する状態マシンと、日割り計算のプレビューおよび再開に対応したアップグレード／ダウングレード
• 冪等な Webhook — 署名検証、イベントの重複排除、API からの再取得を行うハンドラー、安全に再試行できる処理
• 従量課金とアクセス制御 — 使用量レコード、プランごとの機能制御、猶予期間中のアクセスロジック
• 督促と SCA — 支払い失敗時のメールシーケンス、PSD2／3D Secure 認証フロー
• ローカルテスト — Stripe CLI による Webhook 転送、イベントのトリガー、テストカードの一覧

使用する場面

• Next.js、Express、Django で SaaS のサブスクリプション課金を一から構築する
• 適切な日割り計算を伴うプランのアップグレード／ダウングレードを追加する
• Webhook エンドポイントの冪等性と再試行の安全性を強化またはデバッグする
• 従量課金またはプランごとの機能制御を実装する
• 督促による支払い回収、または欧州の SCA／3D Secure への準拠を追加する

最初に確認すること

インテグレーションを構築する前に、次の入力内容を確認してください。不明な点や曖昧な点があれば、推測せずに質問してください。

• フレームワーク — Next.js／Express／Django（ハンドラーとクライアントのパターンはスタックごとに異なります）
• 課金モデル — 定額サブスクリプション／従量課金／トライアルと日割り計算（サブスクリプションの状態マシンとコードの形が変わります）
• 対象範囲 — Checkout、冪等な Webhook、督促、SCA／3D Secure のいずれか（参照資料と生成するコードを選択します）

停止ルール：出力に最も影響する 2～3 項目だけ質問してください。ユーザーが「とりあえず下書きを作って」と言った場合は、先に進み、成果物の冒頭に前提を列挙してください。

参照資料

タスクに合った参照資料を読み込み、このファイルは簡潔に保ち、必要に応じて詳細を確認してください。

• references/payment-flows.md — Stripe クライアントのセットアップ、プラン設定、Checkout セッション、Customer Portal、SCA／3D Secure を扱います。クライアントの接続や Checkout／ポータルへのリダイレクトを構築する際に読んでください。
• references/subscriptions.md — ライフサイクルの状態マシン図、アップグレード／ダウングレード／プレビュー／キャンセルのコード、従量課金、機能制御、Prisma スキーマを扱います。サブスクリプションの状態設計やプラン変更の実装時に読んでください。
• references/webhooks.md — 署名検証とすべてのイベントハンドラーを含む、冪等な Webhook ハンドラーの全体を扱います。Webhook エンドポイントの構築または監査時に読んでください。
• references/testing-and-troubleshooting.md — Stripe CLI によるテスト、よくある問題、トラブルシューティングの表、成功基準を扱います。ローカルテストや課金の不具合の診断時に読んでください。

関連スキル

スキル	使用する場面
ab-test-setup	料金ページのバリエーションと Checkout フローをテストする
analytics-tracking	Checkout とサブスクリプションのコンバージョンイベントを追跡する
email-template-builder	督促メールと課金通知メールを作成する
api-design-reviewer	課金 API エンドポイントをレビューする

対象範囲と制限事項

このスキルの対象：

• SaaS 課金向けの Stripe Checkout、Subscriptions、Customer Portal の統合
• 冪等性、署名検証、再試行時の安全性を考慮した Webhook の処理
• 従量課金（メーター制課金）、日割り計算のプレビュー、プラン変更のワークフロー
• 欧州の決済規制（PSD2）に準拠するための SCA／3D セキュア

このスキルの対象外：

• Stripe Connect（マーケットプレイスの売上払い出し、複数当事者間の決済）――プラットフォーム固有の Stripe Connect ドキュメントを参照してください
• サブスクリプションを伴わない単発決済のフロー（例：Eコマースの商品購入）
• 税額計算と納税（Stripe Tax の設定、VAT／GST の申告）――規制に関するガイダンスは ra-qm-team/ のコンプライアンススキルを参照してください
• 決済不正の検出と異議申し立ての管理（Stripe Radar のルール、チャージバックのワークフロー）――セキュリティレビューのパターンについては skill-security-auditor を参照してください

統合ポイント

スキル	統合内容	データフロー
api-design-reviewer	REST の慣例、エラー処理、レート制限に照らして課金 API エンドポイントをレビューします	課金ルートの定義 --> API レビューチェックリスト --> 検証済みエンドポイントコントラクト
database-schema-designer	Stripe の顧客、サブスクリプション、イベント追跡テーブル用の Prisma スキーマを設計・検証します	スキーマ要件 --> 正規化されたテーブル設計 --> マイグレーションファイル
observability-designer	Webhook ハンドラーとチェックアウトフローに、構造化ログ、メトリクス、アラートを設定します	Webhook イベント --> OpenTelemetry トレース --> 障害急増時のダッシュボードアラート
env-secrets-manager	開発／ステージング／本番環境で Stripe API キー、Webhook シークレット、価格 ID を管理します	シークレット定義 --> 暗号化されたボールトへの保存 --> 環境変数を介した実行時の注入
ci-cd-pipeline-builder	CI での Stripe CLI Webhook テストを自動化し、デプロイ前に統合を検証します	テストトリガー --> CI での stripe listen --> Webhook ハンドラーのアサーション
runbook-generator	Webhook の失敗、大規模な決済失敗、サブスクリプションの照合など、課金インシデントに対応する運用ランブックを作成します	インシデントのシナリオ --> 段階的な修復手順 --> エスカレーション経路