Stripe 課金
subscription 価格、冪等 checkout、webhook、credit、portal 安全性、照合を設定します。
スターターのコミット
7d452a6と同期済みです。
Plus と Max の月額/年額に安定した Stripe Price を作り、STRIPE_PRICE_*、STRIPE_PRIVATE_KEY、STRIPE_WEBHOOK_SECRET を設定します。CNY Price は任意です。金額と catalog は src/config/billing.ts、Price ID は server のみです。
checkout は組織 owner 限定で Idempotency-Key が必須です。Stripe より先に purchase intent/order を作るため同じ request の retry は一度だけ作用し、意図的な再購入には新しい key が必要です。複数 subscription は共存でき、resolver が entitlement を合成します。
Webhook 契約
/api/pay/notify/stripe を公開し、checkout 完了/期限切れ、subscription 作成/更新/削除、invoice paid/payment failed、refund/dispute を購読します。署名と event ID 重複、順不同の event time を検証し、各 credit benefit を一度だけ付与します。更新 invoice は新しい order と月次 credit を作ります。
refund/dispute は審査対象として通知され、使用済み credit を黙って回収しません。不確実な状態は付属の照合 command と admin event 画面で直します。
Portal とテスト
Billing Portal configuration を作り、本番で ID を設定します。Portal の subscription update は無効化必須で、安全でなければ fail closed します。
stripe listen --forward-to localhost:3000/api/pay/notify/stripe重複 checkout、遅延/重複 webhook、更新、失敗、解約、refund、portal をテストし、本番は live key と live event のみ使います。