販売管理を Stripe 中心で組む案

1. 現状の棚卸し（事実）

2. 要約

1. 外部のカート・講座プラットフォーム・オープンソースを広く調べたが、今回の目的に合うものは無く、Stripe を中心にまとめることにした。
2. 「カードや口座の情報を持ちたくない」は、Stripe の決済画面（Checkout）を使う今の作りで既に満たしている。
3. 方針は「Stripe にまとめられるものは Stripe に、どうしても自社が要るものだけ自社に」。商品・値段・決済画面・返金・売上確認は Stripe、権利の付与と停止・教材の中身・会員との紐付けは自社。
4. 自社には薄い「販売台帳」（Stripe の値段 ID と教材の対応・販売状態）を置き、権利はそこから付ける。Stripe の商品に書いたメモ（metadata）だけで権利を付けるのは危ないため。
5. 9/30 の基盤のうち、自社の値段管理と商品編集画面は捨て、Webhook・注文・権利・返金／異議・日次照合は使い回す。
6. 最初の本番は「公開済み教材の単品と固定セットを、カードの単発払いで売る」だけに絞る。
7. 独立した 2 本の設計レビューの判定は、どちらも「条件付き採用可」。条件は 6 章。

3. Stripe で何ができるか（調査結果）

出典は Stripe 公式（docs.stripe.com・stripe.com/jp/pricing、2026-10-08〜09 に取得）。

3.1 商品と値段

• Product（商品）と Price（値段） を管理画面または API で作れる。1 商品に複数の値段を付けられ、単発用とサブスク用の両方がある。
• 値段の改定は「新しい Price を作って古い方を無効にする」運用。過去の購入は買ったときの Price に結び付いたまま残る。
• 任意の情報を metadata として付けられる（1 件あたり最大 50 項目・キー 40 文字・値 500 文字）。Stripe は中身を検証しない。
• Product・Price の active（有効）は「新しい購入に使えるか」だけを意味する。

3.2 決済ページ

• Checkout: 自社サーバーが購入ごとに決済セッションを作り、Stripe がホストする画面へ送る。カード情報は自社を通らない。会員 ID は client_reference_id で渡せる。Stripe の Customer を指定すると、その Customer のメールは決済画面で編集できない。
• Payment Links: 管理画面で商品ごとの決済 URL をコードなしで作れる。client_reference_id は URL のパラメータで渡す（英数字・ダッシュ・アンダースコア、最大 200 文字）ため、買い手が書き換えられる。二重購入の事前チェックもできない。
• 決済完了は Webhook checkout.session.completed で届く。品目（line_items）は通知の本文に含まれず、API で取り直す必要がある。コンビニのように後から入金が確定する支払いは、checkout.session.async_payment_succeeded / async_payment_failed を別に受ける。

3.3 取引の記録と運用

• 決済・返金・異議・手数料・入金予定・領収書・顧客の記録が Stripe に残り、管理画面で検索・CSV 出力できる。SQL での集計は有料の Sigma。
• 返金・異議への対応・領収書メールは管理画面から行える。
• プロモーションコード（クーポン）は Checkout と Payment Links で使える。
• Customer Portal は、サブスクの解約・支払い方法の変更・請求書の確認を顧客自身にさせる画面。
• Entitlements API（Stripe 側の権利機能）はサブスク専用で、単発購入の権利には使えない。

3.4 セキュリティ

• Checkout（ホスト型）は、PCI DSS の自己問診でいちばん軽い区分（SAQ A）にあたる。加盟店側にも一定の責任は残る。
• 3D セキュア（日本のクレジットカード・セキュリティガイドラインで求められる本人認証）は、Checkout と Payment Links の単発決済なら追加対応が要らない。
• 管理画面は役割（管理者・返金担当・異議担当・閲覧のみ など）でチームの権限を分けられ、チーム全員に 2 段階認証を必須にできる。管理者は他の人を招待できるため、管理者アカウントが乗っ取られた時の被害が大きいと Stripe 自身が注意喚起している。
• API キーは権限を絞った「制限付きキー」を作れる。
• Webhook は署名（Stripe-Signature、HMAC-SHA256）で本物か確かめる。届く順番は保証されず、同じ通知が複数回届くことがある。失敗時の自動再送は本番で最長 3 日。
• Cloudflare Workers からは constructEventAsync（Web Crypto）で署名を検証できる。

3.5 日本の決済手段と手数料（標準料金・2026-10-08 時点）

3.6 使わないと決めたもの

• Managed Payments（Stripe が販売元になる方式）: テスト環境では既定で有効になり、決済手段の指定と衝突したため無効化して運用している。
• Payment Links: 上記 3.2 の理由で、会員向けの販売には使わない（会員以外への単発キャンペーン程度なら可）。

4. 外部システムの比較調査（なぜ入れないか）

参考として挙がった CAM UP（cammacs.jp/contents/camup8/）は製品ではなく、物販向けクラウド ERP「キャムマックス」を提供する株式会社キャムの記事「おすすめのカートシステム 15 選」だった。

外部システムで置き換えられる部分（決済画面・商品管理・取引記録）は、既に Stripe と自社基盤で大半ができている。時間がかかっている部分（既存の閲覧判定への接続・既存会員の利用権の移し替え）は、どの外部システムを入れても自社に残る。

5. 販売管理体制案

5.1 置き場所の仕分け

5.2 購入の流れ

1. 会員画面の値段は、販売台帳の写しから表示する（Stripe を表示のたびには叩かない。Stripe 障害を閲覧に波及させないため）。
2. 購入ボタン → 自社サーバーが、①ログイン会員か ②台帳で販売中の Price か（表示した Price ID と照合）③同じ教材を既に持っていないか ④未完了の決済が無いか、を確かめる。
3. 購入内容（教材の集合・金額・台帳の版）を固定した注文の下書きを作り、その会員の Stripe Customer と Price ID で Checkout セッションを作る。
4. Webhook で決済完了を受けたら、通知の中身を信用せず Stripe API で状態を取り直し、固定した明細から権利を付ける。
5. 日次の照合で「払ったのに権利が無い」「返金したのに権利が残っている」「台帳に無い決済」を検出する。

5.3 会員との紐付け

• Stripe の Customer は自社が先に作る（同じ会員で二重に作らないよう冪等に）。Customer の metadata に会員 ID を入れ、自社側に「会員 ↔ Stripe Customer」の対応表を持つ。
• 対応は 1 対多にする。名寄せ（2 会員の統合、統合済みの会員は status='merged' で残る）の後も、過去の Customer は残るため。権利の付与先は統合先の会員へ辿って決める。Stripe の Customer は消さない。
• Customer を指定するとメールが決済画面で編集できないため、会員のメール変更を Stripe へ同期する。
• 退会時は未完了の決済を失効させる。再登録した会員へ権利を自動で移さない。メールの一致で名寄せしない。
• 管理画面の会員詳細に、注文・権利・付与の理由・同期の異常・Stripe の顧客ページへのリンクを出す。退会済みの会員も注文 ID から追えるようにする。

5.4 最初の本番の範囲

• 公開済み教材の 単品と固定セット（セットも Stripe の商品 1 つ）を、カードの単発払い・税込固定・数量 1・割引なしで販売。
• 購入はログイン会員だけ。会員ごとに未完了の決済は 1 つまで。同じ教材の重複購入は止める。
• 権利は新しい権利表（entitlements）に付け、教材の閲覧判定だけをそこへ切り替える。既存会員の教材の利用権は保持する。
• 全額返金と異議に連動して権利を止める・戻す。一部返金・返金失敗などは例外として一覧に出し、人が処理する。
• 日次照合と、照合や Webhook 処理が止まったことの検知。
• 後回し: クーポン、サブスク、面接チケット、問題集・過去問の販売、コンビニ払い、PayPay、可変セット。

6. 独立レビューで付いた条件と、既存コードの修正点

この案は、異なる 2 つの AI モデルに独立に防御レビューを依頼し、どちらも「条件付き採用可」だった。条件は 5 章に反映済み。要点:

1. Stripe の metadata を権利付与の正本にしない。管理画面で誰でも商品を作れ、metadata は検証されないため、付け忘れや書き間違いが「払ったのに読めない」に直結する。→ 自社の販売台帳を正本にする。
2. Stripe で商品を有効にしても、教材が下書きのことがある。→ 販売開始を自社の操作にして公開検査を通す。教材を下書きに戻したら台帳を止め、Stripe の Price も無効にする（自社 → Stripe の一方向）。購入者のいる教材は公開版を消せないようにする。
3. 日次照合は残す（Webhook の順序・重複・取りこぼしのため）。台帳と紐付かない通知は「解決待ち」として残し、後から再処理できるようにする。
4. 権利は enrollments に書かない。enrollments には状態の列が無く、返金で止めるには行を消すしかないため。
5. Stripe 側の守り: 個人別アカウント・2 段階認証必須・最小権限。Worker の鍵は返金の書き込み権限を持たない制限付きキー 1 本にし、テストと本番で鍵・Webhook の署名値を分ける。

既存コードで確認した修正点（返金時の権利停止の条件・二重購入の判定範囲・管理画面の有料会員数の数え方の3点）は、セキュリティ上の理由でこのページには書かず、リポジトリの設計メモ docs/COMMERCE_STRIPE_CENTRIC_PROPOSAL_20261009.md §6 に記載しています。

7. 9/30 の基盤から捨てるもの・残すもの

8. 決めたいこと

1. この体制（Stripe 中心・自社は販売台帳と権利と会員の紐付け）で進めてよいか。
2. 要件の変更: 以前の要件「管理画面だけで商品作成を 5 分以内に完結」を、「Stripe で商品と値段を作り、管理画面で教材を結んで販売開始」に変えてよいか。
3. Stripe 管理画面の権限の運用: 誰が商品・値段を作り、誰が返金・異議に対応するか。

9. 参考（リポジトリ内）

• 課金基盤: line-harness リポジトリの枝 handoff/commerce-kiyo-20260930（packages/db/migrations/126〜130、packages/db/src/commerce.ts、apps/worker/src/lib/commerce-stripe.ts、apps/worker/src/routes/commerce.ts）
• 管理画面の会員一覧: educare_admin/site/functions/_lib/crm_db.ts