PayPalサブスク × 宴（UTAGE）公式LINE 連携の構想
ペンディング・未実装・確定ではない。 2026-11-05 時点の構想メモ。今は作らない。再開するときの出発点として、今あるものと決まっていないことを残す。
1｜見るリポジトリと今の状態
| 置き場 | 中身 | 今の状態 |
|---|---|---|
subscrypt-dashboard-nexus（main、dbfccc6） |
React（Vite・TypeScript・shadcn/ui）の管理画面と、server/ 配下の PHP API |
実装あり。仕様は src/仕様書.md |
server/paypal-webhook.php |
PayPal の Webhook を受けて DB に保存 | 実装あり。CREATED は pending_subscriptions、ACTIVATED・PAYMENT.FAILED・EXPIRED・SUSPENDED は subscriptions に保存 |
| 同上（支払い記録） | PAYMENT.SALE.COMPLETED で payments に記録 |
ファイル冒頭に「このイベントが来ないため ACTIVATED で代替」と注記あり |
| 同上（解約） | BILLING.SUBSCRIPTION.CANCELLED | 受信対象には入っているが、保存の振り分けに専用の分岐が無い（未定義イベントとして pending 側に入る作りに見える。要確認） |
custom_id の読み取り |
prid=…&uid=… から uid を取り出し subscriber_line_uid に保存（src/仕様書.md「LINE連携仕様」） |
保存するだけ。宴や LINE を呼ぶ処理は無い |
payment_links テーブル |
支払いリンクを自動登録 | プラン単位の固定リンク（人ごとの custom_id は入らない） |
server/api/cancel-subscription.php |
管理画面から PayPal の解約 API を呼ぶ | 実装あり |
server/batch/paypal_batch.php |
PayPal API から契約情報を同期（仕様 paypal_batch.md、月1回推奨） |
実装あり |
| 管理画面の分析 | LTV／CPA比／コホート／ARPU・継続率／CPA・Payback | 直近コミットは「UIイメージの実装」段階 |
| 宴（UTAGE） | 公式LINE・メール配信・購入者サイト（会員サイト）を運用中 | 決済の連携先に PayPal は無い（Stripe・テレコム・UnivaPay 等） |
| 宴の API（MCP） | 友だちIDでシナリオ登録、購入者サイトへの受講生登録・解除・停止、ラベル付与 | MCP からは可能。外部サーバーから呼べるかは未確認 |
youtube-marketter |
宴の運用記録。購入フローのテスト手順は docs/planning/hakase/2026-07-23_dow-ea-leo-sign-series/review/2026-11-05_purchase-flow-test/README.md |
参考資料 |
2｜ツールとサーバーの全体像
| ツール | 置き場 | 正となるデータ（ここが本物） | 役割 |
|---|---|---|---|
| PayPal | PayPal | 契約（subscription_id）・支払い・契約の状態 |
決済。状態が変わると Webhook で知らせる |
| ダッシュボード | さくらのレンタルサーバー（MySQL系のDB） | uid と契約の対応、支払い履歴、分析の数字（契約状態は PayPal の写し） |
Webhook を受けて保存。宴 API を呼ぶ（構想） |
| 宴 | 宴のサービス上 | LINE友だち・読者・シナリオ・ラベル・購入者サイトの受講生 | LINE・メールの配信と会員サイト |
| LP | 未確定（宴のページか別サーバーか未確認） | 持たない（友だちIDを PayPal へ渡すだけ） | 申込みの入口 |
3｜データ受け渡しのワークフロー
| 区間 | 受け渡すもの | 状態 |
|---|---|---|
| ① LINE → ② LP | URL に宴の友だちIDを付ける | 構想。差し込めるか未確認 |
| ② LP → ③ PayPalボタン | LP が URL から ID を読み、JS SDK で契約を作るときに custom_id へ uid=… を入れる |
構想。今の支払いリンクはプラン単位の固定リンク |
| ④ PayPal → ⑤ ダッシュボード | Webhook。custom_id の uid を subscriber_line_uid に保存 |
実装あり |
| ⑤ ダッシュボード → ⑥ 宴 | 友だちIDでシナリオ登録・ラベル付与・購入者サイト登録 | 構想。未実装 |
4｜イベントごとのシナリオ移行とデータ
すべて構想。「今のDB処理」の列だけがコードで確認できた内容。
| イベント（PayPal） | 今のDB処理 | ダッシュボードで足すもの | 宴で動かすもの | ユーザーに届くもの |
|---|---|---|---|---|
| 有効化（BILLING.SUBSCRIPTION.ACTIVATED） | subscriptions に登録。uid を保存 |
宴への反映の成否を残す | 購入者シナリオに登録、ラベル「購入者」、購入者サイトに受講生登録 | 購入のお礼、購入者サイトのログイン案内 |
| 支払い完了（PAYMENT.SALE.COMPLETED） | payments に記録（ただし届かず ACTIVATED で代替と注記） |
最終支払日の更新 | 原則なし（継続中ラベルの要否は未確定） | 原則なし |
| 支払い失敗（BILLING.SUBSCRIPTION.PAYMENT.FAILED） | 状態を FAILED にして subscriptions を更新 |
失敗日を残す | 支払い確認のシナリオに登録、ラベル付与。購入者サイトをすぐ止めるか猶予を置くかは未確定 | 支払い方法の確認のお願い |
| 停止（BILLING.SUBSCRIPTION.SUSPENDED） | subscriptions を更新 |
— | 購入者シナリオを解除、購入者サイトの受講を停止 | 停止のお知らせ |
| 期限切れ（BILLING.SUBSCRIPTION.EXPIRED） | subscriptions を更新 |
— | シナリオ解除、ラベルの付け替え、受講生の登録解除 | 終了のお知らせ |
| 解約（BILLING.SUBSCRIPTION.CANCELLED） | 専用の分岐なし（要確認） | 解約として保存する分岐 | 期限切れと同じ扱いにするか未確定 | 解約受付のお知らせ |
5｜決まっていないこと・確かめること
| # | 確かめること | なぜ要るか | 状態 |
|---|---|---|---|
| ① | 宴の LINE の URL に友だちIDを差し込めるか。差し込めるのは生の LINE UID か、宴の友だちIDか | ここで ID が渡らないと、決済した人と LINE の友だちを結べない | 未確認 |
| ② | 宴の API を外部サーバー（ダッシュボード）から呼べるか。キーの発行・契約プラン | 今確認できているのは MCP 経由の操作だけ | 未確認 |
| ③ | uid に入れる値を宴の友だちIDにそろえる |
宴の API は友だちIDでシナリオ登録する | 構想 |
| ④ | PayPal の固定リンクでは人ごとの custom_id が入らない |
今の payment_links はプラン単位。LP で JS SDK を使い1人ずつ契約を作る必要がある |
構想（コードで固定リンクを確認） |
| ⑤ | 顧客の情報の分担: 支払い状態＝ダッシュボード、配信・会員＝宴、つなぐ鍵＝宴の友だちID、予備＝メールアドレス | 2か所に同じ人がいるので、どちらを正にするか決めておく | 構想 |
| ⑥ | 購入者サイトの受講生IDは LINE 友だちIDと別。受講生を作るのにメールアドレス等が要るか | 友だちIDだけで購入者サイト登録まで進めるかが変わる | 未確認 |
| ⑦ | 停止は「受講の停止日を入れる」か「登録を消す」か | 宴の登録解除は消すと戻せない（MCP の説明より） | 未確定 |
| ⑧ | PAYMENT.SALE.COMPLETED が届かない件と、CANCELLED の扱い | 支払い完了・解約で宴を動かすなら前提になる | 未確認 |
| ⑨ | LP をどこに置くか（宴のページか別サーバーか） | JS SDK のボタンを置けるかが置き場で変わる | 未確認 |
6｜連携したらできること・楽になること
すべて構想。前提の番号は5章の表（①〜⑨）を指す。
6-1 中心になる3つ
| # | できること・楽になること | 前提条件 | 状態 |
|---|---|---|---|
| A | 公式LINEの友だちと決済情報がひもづき、誰が購入したかを自動で管理できる | LP から PayPal の custom_id の uid に宴の友だちIDを入れられること（①③④） |
構想。uid を保存する処理は実装あり、IDの受け渡しは未確認 |
| B | 決済の手動確認と、LINEシナリオの手動移動がなくなる | PayPal で払った分だけ。銀行振込は今後も入金確認が手作業。宴の API を外部から呼べること（②） | 構想 |
| C | 顧客の決済状況がダッシュボードで分かり、決済に失敗した人への連絡・追いかけがしやすくなる。仕組みは 6-4 | 宴の API を外部サーバーから呼べること（②）。uid が宴の友だちIDであること（③）。失敗（PAYMENT.FAILED）は今も DB に保存される作り |
構想（前提が確認できれば可能）。状態の保存は実装あり |
6-2 宴の運用者が楽になること（候補）
| できること・楽になること | 前提条件 | 状態 |
|---|---|---|
| 解約・支払い失敗・停止に合わせて、購入者サイトの受講停止／再開が自動になる。解約後も見られてしまう漏れを防げる見込み | 受講生IDと友だちIDが別（⑥）。止め方（停止日か登録解除か）が未確定（⑦）。解約の保存分岐が今は無い（⑧） | 構想 |
| 支払いに失敗した人にだけ、LINE で支払い方法の更新のお願いを自動で送れる。仕組みは 6-4 | 宴の API を外部サーバーから呼べること（②）。uid が宴の友だちIDであること（③）。すぐ止めるか猶予を置くかは未確定 |
構想（前提が確認できれば可能） |
| ラベルで「継続中／失敗中／解約済み」に分けて配信できる（解約者への再案内、継続者への特典など） | 宴の API でラベルを付けられること（②）。解約の扱い（⑧） | 構想 |
| 問い合わせのとき、その人の決済状況と LINE 側の状況を1か所で確かめられる | ダッシュボードに宴への反映結果を残す作りを足すこと（4章） | 構想 |
6-3 管理者が楽になること（候補）
| できること・楽になること | 前提条件 | 状態 |
|---|---|---|
| スプレッドシートや管理画面どうしの照合（二重管理）が減る | 支払い状態の正をダッシュボードに決めること（⑤）。銀行振込など PayPal 以外の決済は対象外 | 構想 |
| LTV・継続率・コホート・CPA回収（Payback）を、決済データから出せる | 分析画面は「UIイメージ」段階。CPA（獲得単価）は月ごとに手で入れる作り。支払い完了イベントが届かない件（⑧） | 構想。画面は開発中（8章） |
| 解約・返金の処理漏れや、手作業のミス（別人への操作）が減る見込み | 返金イベントは今の Webhook の受信対象に無い。解約の保存分岐も無い（⑧） | 構想 |
6-4 LINE の自動送信はどう動くか（支払い失敗の例）
PayPal の Webhook（支払い失敗）→ ダッシュボード → 宴の API で、その友だちを「決済失敗」用のシナリオに登録（またはラベル付与）→ 宴のシナリオが LINE を送る。
- LINE 公式アカウント側の Webhook（LINE → 宴）は宴が持っているので、触らない・作らない
- 前提は「宴の API を外部サーバーから呼べる」「
uidが宴の友だちID」の2つ。状態は構想（前提が確認できれば可能） - 支払い方法の更新は、本人が PayPal のアカウント側で行う。LINE で送るのはそのお願い
- PayPal 自体も、失敗時に自動で再請求し、本人へメールで知らせる。LINE の案内はそれに上乗せする位置づけ
7｜デメリット・保守で必要なこと
「確度」は、構想上かならず要るものを「想定」、数字や中身を確かめていないものを「要確認」とした。
| 区分 | 内容 | 確度 |
|---|---|---|
| 構築工数 | ダッシュボード → 宴 API の連携、LP の PayPal ボタン（1人ずつ custom_id）、友だちIDの受け渡し、PayPal のサンドボックスでのテスト |
想定 |
| 保守工数 | Webhook が届いているかの確認（監視・通知）、届かなかった時の再送・手動での補正 | 想定 |
| 保守工数 | PayPal・宴の仕様変更への追従、API キー・トークンの管理（期限・漏えい対策）、サーバー（さくら）・PHP・SSL の更新 | 想定 |
| 止まった時の影響 | 連携が止まると、購入者に LINE や購入者サイトの案内が届かない。監視が必須 | 想定 |
| データの食い違い | PayPal・ダッシュボード・宴で状態がずれた時に、どれを正とするかのルールが要る（5章⑤） | 想定 |
| 上限 | 宴 API の利用回数に上限（時間あたり・月間）がある | 要確認（具体的な回数は未確認） |
8｜ダッシュボードの画面（UIイメージ・開発中）
画面はUIイメージ（開発中）。 数値と名前はすべて架空のダミーデータ（サンプル会員・example.com）。本番データ・本番サーバーにはつないでいない。手元で開発用の画面を起動し、データ取得の部分だけダミー応答に差し替えて撮った。
