Stripe Connect & サブスクリプション課金 は何をしますか？
1つのStripeアカウント上で2つの資金フローを管理します。マーケットプレイスは買い手に1回課金し、その売上を複数の出品者に分配します（Connect、個別課金と振込）。プラットフォームのサブスクリプションは、出品者に対してオフセッションで定期料金を課金します（Billing）。これらは同じクライアント、同じWebhookペア、同じ金額タイプを共有します。
全体を形作る洞察：買い手の課金と出品者への支払いは、独立して失敗します。 決済が実行される頃には資金はすでに移動しているため、拒否された振込が課金やWebhookを失敗させてはならず、後日再度実行可能で、かつ二重払いを防ぐ必要があります。
いつ使用するか
- 1回の支払いを複数の販売者に分割し、プラットフォームが手数料を取る場合。
- 販売者がConnectにオンボーディングし、遅延支払い（エスクロー、準備金、KYC）を受ける場合。
- プラットフォームが自身の販売者に対して保存済みカードで定期料金を課金する場合。
- コネクテッドアカウントが正常に見えるが、一度も入金を受け取っていない場合。
使用すべきでない場合
| これではない | 代わりにこれを使用 |
|---|---|
| 単一販売者のチェックアウト、分割なし | Stripe Checkout / Payment Element を直接使用 |
| PayPal Marketplaceのオンボーディング＋支払い | PayPalスキルを使用（共通部分のみ共有） |
| カードUI、Payment Elementのスタイリング | 自身のデザインシステム；このスキルはサーバーサイド |
アーキテクチャ
買い手 ──課金（プラットフォームアカウント、transfer_group = orderId）──▶ プラットフォーム残高
│ 決済ファンアウト（Webhook または 読み取りパス同期；リースされたクレーム）
┌────────────┴──┬────────────────────────┬────────────────┐
▼ ▼ ▼ ▼
振込：出品者 振込：パートナー エスクローホールド ローリングリザーブ
(source_transaction = 課金) (release_at) (% 保留)
│ │ release-escrow cron
▼ ▼
コネクテッド残高 ◀── retry-transfers 支払可能残高 ──▶ 支払い（KYC/リスクゲート）
（未資金のレッグ）
プラットフォーム ──off_session PaymentIntent（顧客 + 保存済み支払い方法）──▶ サブスクリプション請求書
ダニング：3回、3日間隔、その後停止
重要な事実
- 個別課金と振込であり、デスティネーション課金ではない。 1回の課金は1つの
destinationを取ります。複数出品者のカートには、1つのtransfer_groupの下でN個の振込が必要であり、application_fee_amountは使用できません。 source_transactionなしの振込は利用可能残高から引き出され、 課金がまだ決済中の場合に拒否されます。新規プラットフォームアカウントでは、すべての振込がこれに該当します。この1つのフラグにより、課金が決済中でも資金を分割できるようになります。- Stripeの振込は国境を越える場合、US/CA/UK/EEA/CH内のみです。 それ以外の地域のプラットフォームは、自国のみのコネクテッドアカウントに支払います。Stripeは振込時にこれを強制し、オンボーディング時ではありません。そのためテンプレートはオンボーディング時に地域ルールを適用します。
- Connectイベントはプラットフォームイベントとは異なる署名シークレットを持ちます。 2つのエンドポイント、2つのシークレット、1つのURL — 両方に対して検証します。
- コネクテッドアカウントの国は不変です — 間違った国の場合は再オンボーディングが必要であり、修正はできません。
- 金額は決して浮動小数点ではありません —
numeric(19,4)文字列で一貫し、bigint計算、最小単位はSDKの境界でのみ使用します。
厳格なルール
決済に失敗した振込が決済自体を失敗させてはなりません。 そのレッグを未資金として記録し、続行します。課金はすでに成功しているため、Webhookも成功しなければなりません。リトライcronが後日レッグに資金を提供します。
重複したWebhook挿入を「すでに処理済み」として扱ってはなりません。 挿入はクレームであり、配信が途中でクラッシュした場合のリトライがハンドラーを再実行するため、すべてのイベントは正確に1回実行されるまで完了しません。
Stripeに問い合わせずに振込を再送信してはなりません。 応答が失われたために未資金として記録されたレッグは、Stripeの24時間冪等性ウィンドウを過ぎると二重に支払われます。
決済の排他性を、最後に書き込まれたステータスフラグから導出してはなりません。 2つの呼び出し元がルーチンで決済に到達します。アトミックなリースクレームにより、インベントリと振込が1回だけ発生します。
振込の残存可能額を超えて取消しを行ってはなりません。 積み重なった取消し（ゲートウェイ手数料、その後返金）は元の金額を超えると拒否されます。
クイックスタート
- 資金をモデル化 — money.md、data-model.md、store.md。
- クライアント、デュアルWebhookシークレット、環境 — stripe-adapter.md。
- アカウントをオンボーディング；最初に地域ルールを確認 — connect-accounts.md。
- イベントを冪等に受信 — webhooks.md。
- 決済：クレーム、ファンアウト、エスクロー、リザーブ — settlement.md。
- 収束：レッグのリトライ、手数料の調整 — reconciliation.md。
- テナントへの課金 — subscriptions.md；operations.mdで実行。
adaptation.mdを使用してアプリに適合させます。監査記録はprovenance.mdにあります。
適応契約
| 接合点 | スキルが提供するもの | ホストが提供するもの |
|---|---|---|
| ドメインエンティティ | Tenant（販売組織）、Order、VendorOrder、Partner | 自身の語彙 |
| テナントスコープ | 1つのサーバー派生tenantId | org / workspace / seller |
| 認証ガード | ルートごとのアダプター署名 | Clerk、NextAuth、Supabase、カスタム |
| データアクセス | PaymentsStore契約 + SQL | 自身のORMまたはSDK |
| 監査＋通知 | 呼び出しサイト、イベント名、ペイロードの形状 | 自身の監査テーブル / アウトボックス |
| バックグラウンド処理 | 4つのcronとその頻度 | 自身のスケジューラー |
| バリデーション | ルート本体ごとのスキーマ形状 | zod / valibot / yup |
| UI | なし — このスキールはサーバーサイド | すべて |
リファレンスディレクトリ
| シナリオ | トリガーキーワード | リファレンス |
|---|---|---|
| この資金モデルの理由 | 個別課金と振込、デスティネーション課金、application_fee_amount、transfer_group、元帳 | architecture.md |
| テーブル、カラム、RLS | スキーマ、マイグレーション、payment_intents、transfers、escrow_holds、webhook_events | data-model.md |
| データアクセス契約 | ストア、リポジトリ、アトミッククレーム、条件付き更新、ORM | store.md |
| 金額と丸め | numeric、bigint、最小単位、分配、最大剰余、セント | money.md |
| クライアントとアダプターコード | stripeClient、apiVersion、constructEvent、whsec_、PaymentIntent、返金、支払い | stripe-adapter.md |
| オンボーディング、アカウント状態 | Express、Accounts v2、account.updated、charges_enabled、acct_、国、地域 | connect-accounts.md |
| 安全なイベント受信 | 冪等性、重複、リプレイ、生の本文、署名、invalid_signature | webhooks.md |
| 支払い済み注文の分割 | 決済、ファンアウト、source_transaction、エスクロー、リザーブ、シングルフライト | settlement.md |
| 未達分の修正 | リトライ、未資金、バックオフ、採用、ゲートウェイ手数料、クローバック、取消し、残存可能額 | reconciliation.md |
| 定期プラットフォーム手数料 | SetupIntent、off_session、保存済みカード、ダニング、請求書、past_due、停止 | subscriptions.md |
| セットアップ、環境、cron、デバッグ | STRIPE_SECRET_KEY、webhookエンドポイント、stripe listen、cron、「出品者が未入金」 | operations.md |
| このアプリへの適合 | 適応、ホストプローブ、リネーム、ORM、認証ガード、移植 | adaptation.md |
| 監査記録 | 来歴、逸脱、維持、追加、未検証 | provenance.md |