software-payments

決済・請求エンジニアリング

このスキルは、本番環境の決済連携を設計、実装、デバッグするために使用します。対象には、チェックアウトフロー、サブスクリプションのライフサイクル処理、請求ポータル、エンタイトルメントによるアクセス制御、Webhook、地域別価格設定、決済テスト戦略が含まれます。

クイックリファレンス

必要なもの	デフォルト	例外	リファレンス
標準的な SaaS サブスクリプションのチェックアウト	Stripe Checkout または Payment Links	ブランドに合わせたカスタム UI が必須の場合は、Payment Element と Express Checkout Element を使用します	references/stripe-patterns.md
マーチャント・オブ・レコード（税務・販売者を一括管理）	Paddle または LemonSqueezy	Stripe Managed Payments を評価する前に、販売者の所在地、製品の税コード、アカウントの適格性、サポート対象の画面を適格性ページで確認します	references/platform-comparison.md
大量処理またはエンタープライズ向けの複数決済手段による処理	Adyen	—	references/platform-comparison.md
英国または EU の銀行口座引き落としとローカル決済手段	GoCardless、Mollie、またはオープンバンキングプロバイダー	リポジトリによって異なります。バンドル内のソースには、状況に応じた 3 つの使い分けが記載されていないため、既存の連携で使われているものを継続します	references/uk-eu-payments-guide.md
使用量ベースの計測またはトークン課金	Stripe Billing Meters または Lago	—	references/subscription-lifecycle.md
複雑な契約、シート、または収益認識に関する請求	決済処理プロバイダーの上に Chargebee または Recurly を導入	—	references/subscription-lifecycle.md
Webhook の信頼性	署名の検証と冪等な処理	—	references/webhook-reliability-patterns.md
エンタイトルメントと機能へのアクセス制御	レジストリ、API での適用、UI ペイウォールの組み合わせ	—	references/feature-gating-patterns.md
iOS ネイティブのアプリ内購入	バックエンドでの JWS 検証を伴う StoreKit 2	マルチプラットフォームのエンタイトルメント同期に十分な効果がある場合に限り RevenueCat を追加します	references/storekit2-native-patterns.md
チェックアウトと Webhook のテスト	Stripe CLI と E2E 自動化	—	references/testing-patterns.md
AI エージェントによる購入の開始	範囲を限定した使い切りの決済認証情報と販売者側での承認	リスクの高い操作では人間による確認を行います	references/agentic-commerce.md

このスキルを使用する場面

主な作業が次のいずれかである場合に、このスキルを使用してください。

• 決済プロセッサー、販売者記録（merchant-of-record）レイヤー、または請求スタックの選定
• ホスト型またはカスタムのチェックアウトの実装
• サブスクリプションのライフサイクルと Webhook 処理の設計
• 機能制限と請求ポータルのフローの構築
• 地域別価格設定、税務を考慮したプラットフォームの選定、または各地域の決済手段への対応
• チェックアウトまたは請求ワークフローのテストと運用

主な作業が次に該当する場合は、別のスキルを使用してください。

ニーズ	代わりに使用
決済以外の一般的なバックエンド実装	../software-backend/SKILL.md
請求に関係しない API コントラクトの設計	../dev-api-design/SKILL.md
価格戦略とパッケージ設計	startup-business-models
チェックアウトのコンバージョン最適化	marketing-cro
アプリケーションのセキュリティレビュー	../software-security-appsec/SKILL.md
ストア請求に関するネイティブアプリの実装	../software-mobile/SKILL.md
ウォレット、暗号資産の決済、またはオンチェーンでの資金移動	../software-crypto-web3/SKILL.md
Stripe 固有の製品／API に関するガイダンス、またはアカウントツール	Stripe が提供するスキル／プラグインを利用できます。Stripe のエージェント向けガイダンスから見つけ、実行環境のインストールおよび権限に関するポリシーに従ってください

デフォルト設定

• ほとんどの SaaS チームやプロダクトチームでは、Stripe をデフォルトの決済プロセッサーとします。
• ブランドに合わせたカスタム UI が必須でない限り、ホスト型チェックアウトを最初の選択肢とします。
• 署名検証済みの Webhook を状態同期のトリガーとし、配信が重複したり順序が前後したりする可能性があるため、プロバイダーの最新オブジェクトと照合します。
• プロバイダークライアントは遅延初期化し、インポート時にシークレットがないことでビルドが失敗しないようにします。
• 利用可能な決済手段を意図的に制限する場合を除き、payment_method_types は省略します。
• すべての Webhook ハンドラーで署名を検証し、冪等性を確保します。
• 機能制限は、レジストリ、API 境界、UI のペイウォールという 3 つの箇所すべてで適用します。
• プラットフォームの利用可否、API バージョン、プレビュー機能、税務上の挙動は変わりやすいため、最終的な助言の前に確認します。

ワークフロー

1. 資金移動、プロバイダー、顧客、台帳の境界を定義し、ビジネスモデルを分類します。
   • 単発購入
   • サブスクリプション
   • 従量課金
   • マーケットプレイスまたは複数当事者間のフロー（資金フローモデルの選定や支払いの設計に着手する前に、references/marketplace-payouts.mdを読み込みます）
   • モバイル IAP、または Web とアプリを組み合わせた請求
2. スタックを選定します。
   • 決済プロセッサー
   • 必要に応じて販売者記録（merchant-of-record）レイヤー
   • ライフサイクルの複雑さを考慮して正当化できる場合は、請求オーケストレーター
3. チェックアウトの形式を選定します。
   • 手早く導入するなら Checkout または Payment Links
   • カスタム UX なら Payment Element
4. 運用の中核を実装します。
   • Webhook の署名検証
   • 冪等な処理
   • 請求ポータルまたはセルフサービス管理
   • エンタイトルメント同期と機能制限
5. プロバイダーの残高または精算レポート、台帳エントリー、エンタイトルメントを照合し、不一致のレコードの担当者を割り当てます。
6. 成功、拒否、重複、タイムアウト、返金、再試行の各パスをテストします。統合を本番環境に対応できる状態とする前に、可観測性とインシデント対応を追加します。

状況別のプラットフォームのデフォルト設定については、上記のクイックリファレンス表を参照してください。詳しいトレードオフについては、references/platform-comparison.mdおよびreferences/uk-eu-payments-guide.mdを参照してください。モバイルサブスクリプションのデフォルトでは、記録システムとして StoreKit 2 または Play Billing を使用します。クロスプラットフォームでのエンタイトルメント同期、実験、または Web とストアの連携によって実質的な利点が得られる場合に限り、RevenueCat を追加します。

よくある落とし穴

• エンタイトルメントを一元管理せず、モバイルアプリの課金をハイブリッド構成にすること。App Store、Play Billing、ウェブサブスクリプションのすべてでアクセス権を付与できる場合は、リリース前にエンタイトルメントの正規状態と競合解決ルールを1つ定めてください。
• チェックアウト成功後のリダイレクトを購入の証拠として扱うこと。リダイレクトはUXのためのものにすぎません。プロビジョニングは、検証済みのWebhookまたはストアサーバー通知の経路を待ってから行う必要があります。
• モバイルのデジタル商品に関するポリシーの境界と、ウェブSaaSの課金に関する前提を混同すること。アプリ内デジタル商品の扱いに関するAppleとGoogleのポリシーは変わりやすいため、最終的な実装方法を案内する前に再確認する必要があります。
• App Storeのストアフロントに応じて分岐せず、iOSアプリにウェブチェックアウトへのリンクやボタンを表示すること。外部リンクの許可、エンタイトルメント、利用規約は、ストアフロントとアプリのカテゴリによって異なります。Storefront.current に応じて分岐し、リリース前に適用されるガイドラインと地域別の規約を再確認してください。references/storekit2-native-patterns.mdを参照してください。
• RevenueCatがあらゆるモバイルサブスクリプションの構成で自動的に標準となると考えること。これは調整レイヤーであり、必須ではなく、独自の運用対象も増えます。
• 冪等性の境界を設けずに、無関係な課金関連の副作用を1つのWebhookコンシューマーで処理すること。エンタイトルメント、請求書発行、CRM同期、分析への振り分けには、それぞれ異なる再試行とリプレイの動作が必要です。
• チェックアウトの構築後まで、税金、Merchant of Record、請求書の発行者に関する決定を先送りすること。これらの選択は、商品カタログ、法的主体の責任範囲、返金、サポートのワークフローに影響します。

よくあるアンチパターン

• 適用されるストアフロントの購入および外部リンクのポリシーに違反するネイティブのデジタル商品のチェックアウトを使用すること。利用する画面や導線を選ぶ前に、これらのポリシーを確認してください。
• ウェブ、モバイル、課金システムに別々の商品カタログや価格カタログを作成し、同期の取り決めを設けないこと。
• 安定した内部のサブスクリプションIDまたはアカウントIDではなく、プロバイダーのオブジェクトIDだけをエンタイトルメントのキーとして使うこと。
• ダウングレード、解約、返金、猶予期間のポリシーをテストせずに、課金ポータルをリリースすること。
• 料金ページ、チェックアウトの文言、エンタイトルメントのルール、CRMの顧客ライフサイクルを、それぞれ独立して変更し、整合性を失わせること。
• 収益分析イベントを、アクセス制御における運用上の真実として扱うこと。

Stripe 統合の標準設定

決済処理にStripeを選ぶ場合は、上記の一般的な標準設定に加えて、Stripe固有の以下の標準設定を適用してください。

• 内部ユーザーとティアのメタデータを慎重に保存し、DBで使用する前に検証します
• 事前に計画した課金変更には、サブスクリプションスケジュールを使用します
• セルフサービスでの変更に備えて、課金ポータルを有効にしておきます
• パッケージ構成が頻繁に変わる場合はエンタイトルメントを使用します。ただし、認可は引き続き独自のAPIで強制してください

APIバージョンに関する注意事項、Webhookのマッピング、移行の詳細については、references/stripe-patterns.mdを参照してください。

エージェントによるコマース

AIエージェントがユーザーに代わって購入する場合、または販売者がエージェント起点の注文を受け付ける場合は、販売者、通貨、上限金額、有効期限に紐付けた取引ごとの認証情報のみをエージェントに付与してください。支出上限をコードで強制し、最終合計金額について販売者の承認または却下を受け、エージェントの再試行に対してすべての手順を冪等にし、継続課金や新しい加盟店などのリスクの高い操作には人間の確認を必須とし、異議申し立ての証拠として同意記録を保管してください。Stripeの共有決済トークンに関する注意事項を含むreferences/agentic-commerce.mdを参照してください。

本番運用準備チェックリスト

照合ゲート。

期待される金額、通貨、手数料、税金、決済、返金、異議申し立て、現在の利用権限を記録する、プロバイダーに依存しない金銭記録を定義します。スケジュールに従って、Webhook とプロバイダーの残高レポートまたは決済レポートをこの記録と照合し、例外キューと担当者を設けます。チェックアウト成功後のリダイレクトや Webhook はイベントの証拠ですが、現金、会計状態、アクセス権が一致していることの証明にはなりません。

• すべてのハンドラーで、処理前に Webhook 署名を検証する
• すべての Webhook ハンドラーを冪等にする（同じイベントを再実行しても安全）
• チェックアウトの作成と Webhook の失敗を明示的にログに記録する
• 順不同のイベントや失敗するイベントに対するデッドレターまたは再試行の方針を定める
• ローカルおよび CI のテストフローに Stripe CLI（または同等のもの）を組み込む
• 成功、拒否、3DS／ステップアップ認証のフローをテストで網羅する
• チェックアウトの 500 エラー、認証失敗、ポリシーによる拒否に対応するインシデント対応手順書を作成する
• チェックアウトの実装を開始する前に、税金と販売者責任者に関する決定を確定する
• レジストリ、API 境界、UI のペイウォールの 3 か所で機能制御を適用する

よくある間違い：

間違い	結果
クライアントのリダイレクトを購入の証明として信頼する	検証済みの Webhook を受信する前に利用権限を付与し、決済なしでアクセスを許可してしまう
価格やプランのロジックをコードにハードコーディングする	カタログとの不整合や、デプロイが必要な価格変更が発生する
不要に payment_method_types を設定する	利用可能な決済方法を意図せず制限してしまう
再試行せずに Webhook の失敗を無視する	利用権限の喪失や、解約されないサブスクリプションが見えないまま残る
Apple／Google のポリシーがリリース間で変わらないものとして扱う	ストアでの却下や、設計のやり直しを強いられる

参照：references/testing-patterns.md、references/webhook-reliability-patterns.md、references/feature-gating-patterns.md、references/ops-runbook-checkout-errors.md

ナビゲーション

コア

• references/stripe-patterns.md
• references/platform-comparison.md
• references/subscription-lifecycle.md
• references/feature-gating-patterns.md

地域別および運用

• references/uk-eu-payments-guide.md
• references/regional-pricing-guide.md
• references/webhook-reliability-patterns.md
• references/ops-runbook-checkout-errors.md

モバイルおよびアプリ内購入

• references/storekit2-native-patterns.md

エージェント型コマース

• references/agentic-commerce.md

マーケットプレイスの支払い

• references/marketplace-payouts.md

テストおよび移行

• references/testing-patterns.md
• references/in-app-browser-checkout-contract.md
• assets/template-checkout-entrypoint-propagation-checklist.md
• data/sources.json

規制とカードスキームの注意点

この分野のしきい値、日付、法令の施行状況は頻繁に変わります。都度、情報源で確認してください。このセクションでは、エンジニアリング上の制御のみを扱います。

• 3DS のテストカバレッジ：CI では、チャレンジ、フリクションレス、認証が必要なオフセッション、認証後の拒否、3DS 非対応の各経路をテストしてください。テストを作成する時点で、Stripe のテストドキュメント（docs.stripe.com/testing）または stripe:test-cards からカード番号を取得してください。記憶を頼りに転記しないでください。
• MIT の SCA 免除：加盟店起点の課金（更新、保存済みカードへの課金）には、off_session: true に加えて、オンセッションでの設定時に取得した必要な同意／委任が必要です。要件に応じて認証も必要になります。フラグが欠けていると、予期しない更新拒否につながることがあります。公開済み仕様とドラフト仕様の機能を使用する前に、EMVCo およびプロバイダーの対応状況を確認してください。
• EU PSD3／PSR：規定を拘束力のあるものとして扱う前に、EU の有資格規制法務専門家を通じて、公布状況、施行日、適用範囲を確認してください。現時点で設計に織り込むべきアーキテクチャ上のリスクは、オープンバンキング API のパフォーマンス基準、SCA 免除の改定、APP 詐欺に対する責任の強化、片脚取引への適用範囲です。
• EU 即時決済規則：即時 SEPA 送金／受取と受取人確認の義務は、ユーロ圏とユーロ圏外の加盟国で段階的に適用されます。顧客に実装日を約束する前に、規則の条文またはEUの有資格規制法務専門家から日付を確認してください。
• Visa VAMP：比率の計算では不正報告（TC40）と紛争（TC15）が合算されるため、紛争として報告された1件の取引が2回計上される場合があります。エンジニアリング上の主な対策は除外経路です。紛争前に解決した紛争（RDR/CDRN 型サービス）と Compelling Evidence 3.0 による勝訴は、比率から除外されます。加盟店およびアクワイアラーのしきい値は、Visa の最新の VAMP ファクトシートで確認してください。
• Mastercard ECP：直近の一定期間におけるチャージバック件数と比率に応じた段階制で、手数料の増額や MATCH への登録につながる場合があります。加盟店に数値を提示する前に、最新の Mastercard ルールブックで段階と手数料体系を確認してください。いずれかのカードスキームのしきい値に近い加盟店は、セルフサービスでの計算ではなく、専門家によるレビューの対象としてください。
• PCI DSS v4.0.1：将来適用予定だった v4.0 の要件は、決済ページのスクリプト制御（6.4.3、11.6.1）を含め、現在はベースラインです。このスキルでは、チェックアウト画面の対象範囲の縮小（SAQ A 対 SAQ D。references/stripe-patterns.md を参照）を扱います。対象範囲の詳細な判断は、セキュリティ／コンプライアンスの専門家に依頼してください。
• Stripe Managed Payments（販売者代行）：利用資格は、事業所在地、デジタル製品、直接連携のみ（Connect は対象外）、および Checkout Session または Payment Link の画面に応じて制限されます。販売者の所在地、アカウント審査、製品の税コード、対応画面を確認したうえで、MoR アーキテクチャを確約してください。Stripe の利用資格ページ を確認してください。
• 英国の規則：英国の SCA（改正後の PSRs 2017）、義務的な APP 詐欺の払い戻し、FCA の後払い信用（BNPL）制度は、EU の規則とは異なります。規制状況と適用範囲は英国の有資格規制法務専門家に確認してください。英国と EU の消費者責任規則が同じだと想定しないでください。
• サーチャージ：EU と英国では、消費者向けカードのサーチャージは禁止されています。カード決済手段に関わる手数料転嫁機能を実装する前に、現地の規則を確認してください。

学びのループ

過去の判断や落とし穴が参考になる場合は、learnings.consolidated.md があればそちらを参照してください。必要な履歴を確認する場合、または利用可能な代替手段としてのみ learnings.md を使用してください。それ以外の場合は、どちらも参照しないでください。

参照後、覚えておく価値のあるパターン、再発防止が必要なミス、または意外だった分野の事実があれば、agents-skills-feedback-loop/scripts/append_learning.py を使って learnings.md に日付入りの箇条書きを1件追記してください。SKILL.md 自体は変更しないでください。