integrate-stripe

Stripe を統合する

既存のアプリケーション、ビジネスモデル、通貨、対応国、決済の所有者に合った Stripe 統合を構築します。Stripe のコードを計画または記述する前に、必ずプロジェクトを調査してください。

まず既存の統合を検出する

リポジトリを検索し、Stripe のパッケージ、インポート、設定、環境変数名、API クライアント、Checkout または PaymentIntent の作成、Webhook ルート、データベースのフィールド、マイグレーション、テスト、フロントエンドでの Stripe.js の使用状況を確認します。パッケージマニフェストとロックファイルを調べ、インストール済みの Stripe SDK バージョンを特定します。アカウント、リクエスト、Webhook の API バージョンが固定されている場合は、シークレット値を公開せずに特定します。

• Stripe がすでに存在する場合は、決済フロー全体を追跡し、互換性のあるアーキテクチャを維持します。不完全、古い、安全でない、または壊れている動作を見つけて、最小限かつ安全な修正を行います。明確な理由がない限り、Stripe クライアント、Webhook エンドポイント、Customer モデル、決済フローを二重に作成しないでください。
• Stripe が存在しない場合は、プロジェクトで既存の言語、フレームワーク、データベース、バリデーション、エラー処理、ロギング、テストのパターンを使って、統合を一から設計します。
• SDK または API のバージョンが古い場合は、まず公式の変更履歴と移行ガイドを確認します。テストを実施しながら計画的にアップグレードし、無関係な作業の最中に Stripe のバージョンを変更しないでください。

Stripe は時間とともに変更されるため、コードを記述する前に、API の選択が最新の公式 Stripe ドキュメントに準拠していることを確認します。プロジェクトで意図的に固定されている場合を除き、サポート対象の最新 SDK と API バージョンを優先し、バージョン変更を黙って行うのではなく、アップグレードを計画してテストします。

ワークフロー

1. 既存の Stripe 統合が見つかったかどうかを報告し、関連する SDK／API のバージョンと実装済みのフローを列挙します。
2. 商品に単発購入、サブスクリプション、従量課金、請求書、保存済みの支払い方法、マーケットプレイス決済、またはそれらの組み合わせが必要かどうかを定義します。
3. 販売者、顧客との関係の所有者、資金の決済先、異議申し立ての対応者、プラットフォーム手数料の有無を明確にします。
4. 最もシンプルで適切な方法を選びます。ノーコード販売には Payment Links、ほとんどの統合には Checkout Sessions、埋め込み UI には Payment Element を使用した Checkout Sessions、決済状態を独自に制御する場合に限り PaymentIntents を使用します。
5. 商品、Price ID、金額、通貨、割引、税の扱い、本人確認、利用権限、送金先、手数料について、サーバーを信頼できる情報源とします。これらの値をクライアントから受け取って信頼してはいけません。
6. 決済にリダイレクトする前に、内部の保留中の注文またはサブスクリプションを保存します。機密情報を含まないメタデータで Stripe オブジェクトと関連付けます。
7. 署名を検証した Webhook を信頼できる情報源として扱います。商品の引き渡しと状態変更は冪等にし、再試行やイベントの順不同に対して安全にします。
8. 成功時だけでなく、失敗、キャンセル、再試行、返金、異議申し立て、照合の各処理も実装します。
9. サンドボックスでテストし、認証と失敗のケースを確認し、Webhook を再送して、本番稼働前のレビューを完了します。

必ず守るルール

• シークレットキー、制限付きキー、Webhook キーを、ソースコード、クライアント、ログ、エラー、例に決して公開しないでください。サービスごとに最小権限の制限付きキーを優先します。
• 事業者が必要な PCI 手続きを完了していない限り、サーバー側で生のカード番号を扱わないでください。Checkout または Stripe.js Elements を使用します。
• 成功時のリダイレクトや、クライアントから報告された状態に基づいて商品の引き渡しを行わないでください。
• 変更を加えていない生のリクエスト本文に対して Webhook 署名を検証します。
• 一意制約を使ってイベント ID の重複を排除し、可能な場合は変更処理をトランザクションにします。
• 金融関連の POST 操作を再試行する際は、安定した冪等性キーを使用します。
• 新しい実装では、レガシーの Charges、Sources、Tokens、Plans、Card Element を使用しないでください。
• 最新の公式 Terminal ガイダンスで明示的に要求されている場合を除き、動的な支払い方法では payment_method_types を省略します。
• 明示的な承認なしに、本番環境での課金、返金、送金、アカウント変更を決して行わないでください。

リファレンスの参照先

• Checkout、Payment Element、PaymentIntents、SetupIntents、顧客、返金、異議申し立て、SCA、テストについては、references/payments.md を参照してください。
• サブスクリプション、請求書、トライアル、日割り計算、カスタマーポータル、従量課金、エンタイトルメントについては、references/billing.md を参照してください。
• Webhook エンドポイントを実装またはレビューする前に、references/webhooks.md を参照してください。
• プラットフォーム、マーケットプレイス、連結アカウント、オンボーディング、手数料、課金パターン、責任については、references/connect.md を参照してください。
• API キー、PCI 範囲、財務の整合性、可観測性、照合、移行、本番稼働については、references/security-and-production.md を参照してください。
• 応用可能な実装例については、references/implementation-patterns.md を参照してください。
• この拡張スキルの基盤としてクレジットされている上流スキルについては、references/source.md を参照してください。

検証と出力

関連するフォーマット、リンティング、型チェック、テストを実行してください。Stripe の修復を行ったのか、ゼロから追加したのか、確認または変更したバージョン、選択した Stripe オブジェクトと Webhook イベント、内部状態と Stripe の対応方法、重複を防ぐ方法、残っている Dashboard の設定を明記してください。サンドボックスでの検証と本番環境での確認は分けて記載してください。