Fincs

ユーザー / 全体の支払い履歴・支払い手段

ユーザー / 全体の支払い履歴・支払い手段

本ページは 2 段構成。上段が biz/CS 向け（ユーザー提示可）、下段（## 🔧 実装詳細 以降）が dev 向け。biz/CS がユーザーへ提示・転用してよいのは上段のみ。

概要

ユーザーが講座契約・単発支払い等で利用する支払い手段（クレジットカード / 銀行振込）の管理と、講座を跨いだ全体の支払い履歴を確認する機能。

主な使い方:

  • 支払い手段の登録・更新・削除: クレジットカードを 3DS 認証経由で登録、銀行振込での契約も対応
  • 講座ごとの利用カードの切替: 既登録カードのうちどれを使うかを講座ごとに切り替え可能
  • 全体支払い履歴の確認: 全講座を横断した支払い履歴の閲覧と、銀行振込の入金確定後の領収書ダウンロード

主な仕様:

  • 登録カード上限 5 枚（1 ユーザーあたり）。6 枚目は追加できない
  • 利用中のカードは削除不可（契約に紐付いているカードは契約を別カードに切り替えてからでないと削除できない）
  • 3DS 認証は外部の決済認証サービスとの連携で実施。認証失敗時はカード登録フォームに戻って再試行可能（カード番号・セキュリティコードは再入力が必要）
  • 銀行振込の領収書は入金確定後のみダウンロード可能

入会フローでの初回支払い手段設定は ../plan/join.md、講座契約に紐付く支払い手段の管理は ../plan/contract.md、特定講座の単発支払いは ../plan/payment.md で扱う。本ページは「全体ビュー」「複数講座を跨いだ支払い手段の使い回し」に絞る。

📝 レビュー観点（draft 段階の記述ヒント、完成時に削除）:

  • 目的: 講座契約の支払い手段（クレジットカード / 銀行振込）を全体で管理する画面。複数講座で同じカードを使い回す導線
  • 誰が使うか: 受講者・講師（受講者以上）
  • どこで使うか: mypage > 決済情報 / 支払履歴
  • 隣接機能との関係: 講座入会時の支払い手段設定（../plan/join.md）/ 講座契約に紐付く支払い手段（../plan/contract.md）/ 単発支払い・特定講座スコープ（../plan/payment.md）
  • CS 問い合わせで頻発する論点: 「3DS 認証で進めない」「カード上限 5 枚」「カードを変更したいのに利用中で削除できない」「銀行振込で領収書が出ない」
  • [本機能特有] カード上限 5 枚: 6 枚目を追加できない、利用中のカードは削除不可
  • [本機能特有] 3DS 認証: SB ペイメント連携、認証失敗時のフォーム残留挙動
  • [本機能特有] 銀行振込の領収書: transferStatus === DEPOSITED のみ領収書ダウンロード可
  • [本機能特有] 講座ごとの利用カード切替: sb_payment_method_plan で「この講座にはこのカード」を割当可能

利用シナリオ

シナリオ 1: 新規カードを 3DS 認証で登録

ユーザーが mypage > 決済情報 > カード追加から、カード番号・有効期限・セキュリティコード等を入力 → 外部の 3DS 認証サービスへリダイレクト → 認証成功で戻ってカードが登録される。登録完了後、即時に他の入会フロー等で選択肢に表示される。

シナリオ 2: 別の講座で別カードを使う

複数の講座を契約しているユーザーが、講座 A は VISA カード、講座 B は MASTER カードといった具合に講座ごとに利用カードを使い分けたい。決済情報画面でアクティブな講座のカードを切り替えると、次回以降の自動課金で切り替え後のカードが利用される。

シナリオ 3: 銀行振込の領収書ダウンロード

銀行振込で支払った契約について、入金確定が完了した後に支払履歴画面から領収書（PDF 等）をダウンロード。入金確定前は領収書はダウンロードできない。

シナリオ 4: 3DS 認証に失敗 → 再試行

カード登録時に 3DS 認証で失敗した場合、画面上はカード登録フォームに戻る。再試行する場合はカード番号・セキュリティコードを再入力する必要あり（有効期限は保持されない）。

よくある失敗ケース

  • 「3DS 認証で進めない」: 銀行・カード会社側の認証設定の問題で、Fincs 側からは復旧不可。カード会社経由で確認が必要
  • 「カード上限 5 枚」: 6 枚目を追加できない。古いカードを削除（利用中でないこと）してから追加する必要あり
  • 「カードを変更したいのに利用中で削除できない」: 別カードに切り替えてから削除する手順を案内
  • 「銀行振込で領収書が出ない」: 入金確定前は出ない。入金確定は運営側の確認後に反映される

📝 レビュー観点:

  • 新規カードを追加して 3DS 認証を通過する典型例
  • 既存カードを別の講座に切替える例
  • 銀行振込の入金確定後の領収書ダウンロード例
  • 3DS 認証失敗時の再試行（カード番号再入力が必要）
  • カード上限 5 枚到達時の挙動

権限別仕様

権限定義は ../user-roles.md 参照。用語は ../terminology.md。

講座権限軸

支払い情報は講座スコープを跨ぐため、講座権限軸の差分は限定的。

操作 未受講者 受講者 サブ講師 メイン講師
自身の支払い履歴閲覧 （課金履歴があれば閲覧可） ○ ○ ○
自身の支払い手段の追加・削除 ○ ○ ○ ○
講座ごとの利用カード切替 （該当講座契約者のみ） ○ ○ ○

横断軸

操作 運営アドミン テストユーザー 投稿禁止
自身の支払い操作 （通常と同じ） （通常と同じ、ただし課金処理は要確認） （通常と同じ）
他ユーザーの支払い手段の運営アドミン代理操作 ×（運営アドミン専用の支払い手段直接編集経路は存在しない） × ×
銀行振込契約の運営アドミン作成・入金確定 ○（../admin/contract.md 参照） × ×

📝 レビュー観点:

  • 運営アドミンによる代理カード追加・削除の経路はない（CS 対応で困難ケース）
  • 銀行振込関連のみ運営アドミン経由の運用フローあり（入金確定 / クーリングオフ）

機能詳細（ふるまい）

支払い手段の登録

支払い手段は 2 種類:

  • クレジットカード: カード番号・有効期限・セキュリティコード等を入力して 3DS 認証経由で登録。登録後は次回以降の課金・新規入会時に選択肢として表示される
  • 銀行振込: 講座契約時に銀行振込を選択した場合のみ。指定の振込先口座へ入金 → 運営による入金確定で契約完了

3DS 認証フロー

カード登録時の 3DS 認証は外部の決済認証サービスとの連携で実施:

  1. ユーザーがカード情報を入力して「登録」を押す
  2. 外部の認証サービスへリダイレクト（パスワード等の追加認証）
  3. 認証完了で Fincs に戻り、カード登録が完了
  4. 失敗時はカード登録フォームに戻り再試行可能（カード番号・セキュリティコードは再入力が必要、有効期限のみ保持されない設計）

機密情報保護のため、エラーログには full のカード情報は記録されない（カードブランドの情報程度のみ）。

カード上限・利用中カード

  • 1 ユーザーあたり 最大 5 枚
  • 利用中のカードは削除不可（契約に紐付いている）

講座ごとの利用カード切替

複数のカードを登録している場合、講座ごとにどのカードを使うか切り替えることができる:

  • ユーザーは決済情報画面から、講座と利用カードの組み合わせを変更できる
  • 切り替え後の自動課金（月額更新等）から新しいカードが利用される
  • 既に発生した課金には遡及反映されない

支払い履歴

支払い履歴画面（mypage > 支払履歴）では:

  • 全体ビュー: 全講座を横断した支払い履歴一覧
  • 講座別ビュー: 特定講座にスコープを絞った履歴
  • ページング: 1 ページあたり 20 件表示
  • 領収書ダウンロード: 銀行振込の入金確定後の支払いのみ、領収書ファイル（PDF 等）をダウンロード可能

履歴の各行には、支払い日時・金額・講座・支払い方法（カード / 銀行振込）が表示される。

📝 レビュー観点:

  • 入力 → 処理 → 出力: 3DS 認証パラメータ（token / tokenKey / okRedirectUrl / ngRedirectUrl）
  • エッジケース: 3DS 失敗時の再試行（カード番号・セキュリティコード再入力が必要、expireMonth/expireYear のみ保持対象だがリダイレクト後 reset で消える）
  • エラー表示: 3DS 失敗時のアラート、Sentry ログには savedPayment 全体は送らず存在フラグと brand のみ
  • 編集・削除の挙動: 利用中カードの削除阻止、削除後の講座契約への影響
  • [本機能特有] 3DS 失敗時のフォーム残留: 認証失敗で画面上は入力フォームに戻る、再試行可

admin 操作

できる操作

支払い手段直接編集の運営アドミン経路はないが、以下が運営アドミン経由で運用可能（詳細は ../admin/contract.md）:

  • 銀行振込契約の作成: POST /admin_master/bank_transfer_contract/{user_id}/{plan_id}/{plan_price_id}
  • 銀行振込の入金確定: POST /admin_master/bank_transfer_contract/{bank_transfer_id}
  • 銀行振込一覧: GET /admin_master/bank_transfer_contract
  • 契約削除: DELETE /admin_master/contract/{user_id}/{plan_id}/{plan_price_id}
  • クーリングオフ: DELETE /admin_master/cooling_off/...
  • 振込先口座マスタ管理: POST/PUT/DELETE /admin_master/account/...

実装されていない

  • 運営アドミンによる支払い手段（カード）の代理追加・削除: 専用操作経路なし — 今後の改善課題

📝 レビュー観点:

  • 全体支払い履歴の運営アドミン専用一覧 API は未検出（AdminMasterPaymentController は不在）
  • CS 対応で「カードが残っている」相談時の運営側操作経路を確認

品質 / 約束事項

  • 応答性: 支払い手段の追加・削除は同期処理。3DS 認証は外部認証サービスへのリダイレクトを介するため、認証開始から完了まで数秒〜数十秒（ユーザー体験上はカード会社の認証画面操作時間に依存）
  • 信頼性: 3DS 認証失敗時の自動リトライはなく、ユーザーが手動でカード番号を再入力して再試行する。機密情報（カード番号等）はエラーログに full の状態では記録されない
  • 制限値:
    • 登録カード上限: 5 枚 / ユーザー
    • 支払い履歴のページング: 20 件 / ページ
    • 領収書ダウンロード: 銀行振込で入金確定済みの支払いのみ
  • データ保持: 登録カード情報は支払い処理に必要な限り保持。退会時の物理削除タイミングは別途整理（./account-lifecycle.md と整合）

📝 レビュー観点:

  • 応答性: 3DS 認証中の体感時間、カード追加から登録完了までのタイムライン
  • 信頼性: 3DS 失敗時の自動リトライなし、ユーザー手動再試行
  • データ保持: 退会時のカード情報の保持期間
  • [本機能特有] 失敗時の機密情報保護: Sentry に full payment data は送らない、brand のみ

変更履歴（リリースノート候補）

v2.29.2: 2026-05-01（PSD 初版）

  • [PSD 追加] 本ドキュメント初版作成。v2.29.2 時点の実装を起こし。機能追加・変更は含まない

📝 レビュー観点:

  • 過去の主要変更（3DS 対応 / 銀行振込追加 / 領収書 PDF / 講座ごとカード切替の追加 等）があれば追記候補

関連ドキュメント

このページの内容を AI に質問しますか？
関連 spec を自動抽出して ChatGPT / Claude などに渡せます。
AI Prompt で開く →