Stripe 課金

スターターのコミット 2a1a04a で検証済みです。

このページを終えると、顧客が設定済みのプランを購入し、Stripe がアプリへ通知し、組織がエンタイトルメントとクレジットを一度だけ受け取り、運用担当者が不確実な状態を照合できるようになります。

先に商用モデルを決める

スターターは、組織ごとの固定価格で Plus / Max の月額・年額サブスクリプションを提供します。複数の独立したサブスクリプションを許可し、最上位の有効プランを適用しながら、クレジット付与分を加算します。Billing Portal では請求書の確認、支払い方法の変更、解約ができますが、既存契約のプランや数量をその場で変更する機能は無効です。

安全に早く公開するなら、このモデルを保ちます。利用人数に応じた課金、日割り計算付きのアップグレード、自動的なクレジット調整が必要なら、Stripe のサブスクリプション更新を有効にする前に規則を定義してテストしてください。

Plus と Max の月額・年額それぞれに固定の Stripe Price を作り、STRIPE_PRICE_*、STRIPE_PRIVATE_KEY、STRIPE_WEBHOOK_SECRET を設定します。人民元の Price は任意です。金額とカタログは src/config/billing.ts に置き、Price ID はサーバーだけで扱います。

Checkout は組織の owner だけが実行でき、Idempotency-Key が必須です。Stripe を呼ぶ前に購入意図と注文を作るため、同じリクエストを再試行しても一度だけ反映されます。意図的に再購入する場合は新しいキーが必要です。複数のサブスクリプションは共存でき、解決処理がエンタイトルメントを合成します。

Webhook 契約

/api/pay/webhook/stripe を公開し、Checkout の完了・期限切れ、契約の作成・更新・削除、請求書の支払い完了・失敗、返金・異議申立てのイベントを購読します。署名を検証し、Stripe イベント ID で重複を排除し、順不同で届くイベントの時刻を考慮して、各クレジットを一度だけ付与します。更新請求書からは新しい注文と、その請求期間に設定されたクレジット付与を作ります。年額価格では、年一回、12か月分をまとめて付与します。

返金と異議申立ては審査対象として通知され、使用済みクレジットを自動では回収しません。不確実な状態は、付属の照合コマンドと管理コンソールのイベント画面で修正します。

Portal とテスト

Billing Portal の設定を作り、本番環境に ID を設定します。Portal からのサブスクリプション更新は必ず無効にしてください。安全な設定でなければ、処理は安全側に停止します。

stripe listen --forward-to localhost:3000/api/pay/webhook/stripe

Checkout の重複実行、遅延・重複した Webhook、更新、支払い失敗、解約、返金、Portal をテストし、本番では本番用キーと本番イベントだけを使います。ネットワーク再試行が一つの注文だけを作り、Webhook の再処理が一度の付与だけを作り、古いイベントが新しい状態を上書きせず、危険な Portal 設定では安全側に停止し、ローカル照合で説明できない差異がなければ準備完了です。先にプランと権限で商品内容を決め、クレジットを付与するなら組織のクレジット台帳で会計上の扱いも確認してください。