約20万行のマーケットプレイスを、
読める仕様書と移行計画へ。

業務上の位置づけ — F020_TransactionPayPalFlow

この機能が重要な理由

PayPal決済では、購入者がいったんマーケットプレイスを離れ、PayPal上で支払いを承認してから戻ります。そのため、承認結果が届くまでの待機状態と、失敗・キャンセル時の戻り先を明確に扱う必要があります。この仕様では、処理中画面、エラー時の再試行、キャンセル時の復帰、出品者によるPayPal受取設定までを一つの流れとして整理しています。

利用者

• PayPal 支払いを完了する購入者 — PayPal にリダイレクトされ、承認し、トランザクション確認に着地する前の短い待機画面を経てマーケットプレイスに戻る
• PayPal 支払いをキャンセルする購入者 — PayPal でキャンセルをクリックし、閲覧していたリスティングにクリーンに戻る
• PayPal をセットアップする売り手 — マーケットプレイスで PayPal 支払いを受け取れるようになる前に、2段階の PayPal アカウント接続プロセス（注文権限の付与、次に課金契約のセットアップ）を経る

主な操作

購入者の支払いフロー

1. チェックアウトで PayPal を選択した後、購入者は PayPal のウェブサイトに移動してログインし、支払いを承認する。
2. 承認時、購入者はマーケットプレイスに戻り、支払いが記録される間の短い「処理中」画面を確認する。
3. 確認されると、購入者は完了した予約を表示するトランザクション詳細ページに遷移する。
4. 購入者が承認の代わりに PayPal で「キャンセル」をクリックした場合、支払いがキャンセルされた旨の通知とともにリスティングページに戻る。
5. PayPal がエラーを報告した場合（例：残高不足や制限されたアカウント）、購入者には具体的な説明が表示され、リトライやマーケットプレイスへの連絡が案内される。

売り手のセットアップフロー

1. 売り手が支払い設定にアクセスし、PayPal 接続を開始する。
2. マーケットプレイスが売り手に代わって PayPal に権限をリクエストする — 売り手は PayPal にリダイレクトされ、注文処理権限を付与する。
3. 権限付与後、売り手はマーケットプレイスに戻り、2番目のステップを完了する：マーケットプレイスが将来の支払いを処理できるようにする課金契約のセットアップ。
4. 両方のステップが完了すると、売り手のアカウントは PayPal 対応となり、支払いを受け取れるようになる。

追加確認が必要な事項

課金契約の要件	すべての PayPal 売り手が課金契約ステップを完了する必要があるか、特定の支払いタイプにのみ必要かは完全に確認されていない。
ポーリング時間	「処理中」待機画面にかかる時間と、購入者に表示されるタイムアウトがあるかどうかはソースコードから確認されていない。

優先度	P2
種別	mixed
生成日	2026-06-04

機能の概要

この機能ID（F020）は、PayPal決済に固有の画面とバックグラウンド処理をまとめたものです。対象には、処理状況を確認する待機画面、決済成功・キャンセル後の復帰画面、処理完了を確定する画面、出品者のPayPal受取設定画面が含まれます。

条件によって変わる処理

DISC-012 — Transaction.payment_gateway

値	表示・処理	確認条件	保存先・結果
paypal	PayPal 操作ステータスポーリングページ、成功/キャンセル返却ページ、注文パーミッション/請求同意画面がすべて適用される	コミュニティが PayPal 対応済みである必要がある（PaypalHelper.community_ready_for_payments?）。未対応の場合は 400 Bad Request	PaypalPayment レコード。非同期追跡用に process_token が保存される
stripe	これらの画面はいずれも適用されない。Stripe は同期的な 3DS フローを使用する	—	—
none	これらの画面はいずれも適用されない	—	—

DISC-011 — Transaction.current_state（PayPal 固有の遷移）

値	表示・処理	確認条件	保存先・結果
preauthorized	トランザクション通常ライフサイクル（F019）	—	売り手が受け入れ/拒否可能
pending_ext	外部 PayPal キャプチャ保留中	—	paid または rejected へ遷移
errored	PayPal 処理失敗後のエラー状態	—	最終状態

複数機能にまたがる共通処理

機能要件

仕様ID	内容	エンドポイント／処理	検証可能
FR-001	JSON経由でPayPalの処理状況を定期確認する	GET /transactions/op_status/:process_token → PaypalService::CheckoutOrdersController#paypal_op_status	あり
FR-002	PayPalからの成功復帰を処理し、待機画面を表示する	GET /paypal_service/checkout_orders/success → #success	あり
FR-003	PayPalからのキャンセル復帰を処理する	GET /paypal_service/checkout_orders/cancel → #cancel	あり
FR-004	取引処理の状況を定期確認する	GET /transactions/transaction_op_status/:process_token → TransactionsController#transaction_op_status	あり
FR-005	非同期処理の完了後に取引を確定する	GET /transactions/finalize_processed/:process_token → TransactionsController#finalize_processed	あり
FR-006	PayPalの注文処理権限の申請を開始する	GET /:person_id/paypal_account/ask_order_permission → PaypalAccountsController#ask_order_permission	あり
FR-007	PayPalの請求同意申請を開始する	GET /:person_id/paypal_account/ask_billing_agreement → PaypalAccountsController#ask_billing_agreement	あり

業務ルール

BR-001_CommunityPayPalReadiness

関連要件	FR-001, FR-002, FR-003
根拠ソース	app/controllers/paypal_service/checkout_orders_controller.rb:4-8
ルール	PaypalHelper.community_ready_for_payments?(@current_community.id) が true でなければならない。false の場合、render body: nil, status: :bad_request（HTTP 400）でリダイレクトなし。

unless PaypalHelper.community_ready_for_payments?(community.id)
  render body: nil, status: :bad_request
end

BR-002_PayPalTokenRequired

関連要件	FR-002
ルール	params[:token] が存在しなければならない。空白の場合 → error_not_found_path にリダイレクト。

return redirect_to error_not_found_path if params[:token].blank?

BR-003_ProcessTokenMustComplete

関連要件	FR-005
ルール	proc_status[:success] && proc_status[:data][:completed] の両方が true でなければならない。

unless proc_status[:success] && proc_status[:data][:completed]
  redirect_to error_not_found_path
end

BR-004_PayPalOrderPermissionPrerequisite

関連要件	FR-007
ルール	請求同意をリクエストする前に、アカウントの order_permission_state が :verified でなければならない。

case m_account[:order_permission_state]
when Some(:verified)
  # 請求同意リクエストに進む
else
  redirect_to action: ask_order_permission
end

BR-005_PayPalCommunityReadyForPermissions

関連要件	FR-006, FR-007
ルール	PaypalHelper.community_ready_for_payments?(@current_community) が true でなければならない。そうでない場合 → person_payment_settings_path にリダイレクト。

判定ロジック

DEC-001_PayPalSuccessProcessedBranch

種別	flow
対象画面	SCR096_PayPalSuccess

if response[:success]
  redirect_to transaction_created_path(transaction_id: ...)
else
  case paypal_error_code
  when "10486" → redirect to PayPal retry URL
  when "13113" → flash buyer_cannot_pay_error; redirect to listing
  when "10417" → flash transaction_cannot_complete; redirect to listing
  when "10425" → flash seller_express_checkout_disabled; redirect to listing
  when "payment-review" → flash warning pending_review_error; redirect to listing
  else           → flash generic_error; redirect to listing
  end
end

DEC-002_PayPalSuccessAsyncBranch

種別	flow
対象画面	SCR095_PayPalOpStatus

proc_status = paypal_payments_service.create(community_id, token, force_sync: false)
if proc_status[:success]
  render "paypal_service/success", layout: false, locals: {
    op_status_url: paypal_op_status_path(process_token),
    redirect_url: success_processed_path(process_token, listing_id)
  }
else
  flash[:error] = t("paypal.generic_error")
  redirect_to search_path
end

DEC-003_BillingAgreementPermissionGate

種別	flow
対象画面	SCR101_PayPalAskBillingAgreement

case m_account[:order_permission_state]
when Some(:verified) → proceed: request billing agreement URL; render json: {redirect_url:}
else                 → redirect_to action: ask_order_permission

状態遷移

SM-001_PayPalProcessToken

変更前	変更後	条件	実行結果
polling	completed	proc_status.completed == true	JS がリダイレクトをトリガーする
polling	polling	completed == false	ポーリング間隔を継続

処理ロジック

ALG-001_PayPalErrorCodeDispatch

関連要件	FR-002
計算量	O(1) — 線形スイッチ

説明: 既知の PayPal エラーコードをユーザー向けメッセージとリダイレクト先にマッピングする。コード 10486 = 資金不足；13113 = 購入者が支払い不可；10417 = トランザクション完了不可；10425 = 売り手の Express Checkout が無効；payment-review = 保留中のレビュー警告。

case paypal_error_code
when "10486" → redirect response_data[:redirect_url] # PayPal retry
when "13113" → flash buyer_cannot_pay; redirect listing
when "10417" → flash transaction_cannot_complete; redirect listing
when "10425" → flash seller_express_checkout_disabled; redirect listing
when :"payment-review" → flash pending_review_warning; redirect listing
else          → flash generic_error; log unhandled; redirect listing

外部システム連携

INT-001_PayPalCreateOrder

種別	api-call
接続先	PaypalService::API::API.payments.create（PayPal Express Checkout）
送信内容	community_id, PayPal token, force_sync: false
失敗時の処理	!proc_status[:success] → 汎用エラーをフラッシュ；検索にリダイレクト

INT-002_PayPalRequestCancel

接続先	PaypalService::API::API.payments.request_cancel
失敗時の処理	!pp_result[:success] → キャンセルエラーをフラッシュ；検索にリダイレクト

INT-003_PayPalAccountPermissionRequest

接続先	PaypalService::API::API.accounts.request（パーミッションリクエスト）
送信内容	community_id, person_id, callback_url, country
失敗時の処理	redirect_url が空白 → 「リダイレクト URL を取得できませんでした」をフラッシュ

INT-004_PayPalBillingAgreementRequest

接続先	PaypalService::API::API.accounts.billing_agreement_request
送信内容	community_id, person_id, description, success_url, cancel_url

検証方法

• SC-001 — 購入者が有効なトークンで PayPal から戻る → ポーリングスピナー表示。プロセス完了後、トランザクション確認にリダイレクト
• SC-002 — 購入者が PayPal でキャンセル → キャンセル URL が発火。「決済がキャンセルされました」通知付きでリスティングページにリダイレクト
• SC-003 — 成功時に PayPal エラーコード 10486 → 購入者が PayPal リトライ URL にリダイレクト
• SC-004 — コミュニティが PayPal 未対応 → PayPal チェックアウトエンドポイントはすべて 400 を返す
• SC-005 — 未検証の注文パーミッションで請求同意ページにアクセス → ask_order_permission にリダイレクト
• SC-006 — ask_order_permission がリダイレクト URL を返す → JSON {redirect_url} がクライアントに返される

利用者視点の要件

US068_ViewPayPalOpStatus — PayPal 操作ポーリングステータスの表示 （優先度: P2）

処理の流れ	購入者が PayPal で認可しサクセス URL に戻った後、#success が paypal_payments_service.create を force_sync: false でトリガーする。成功した場合、op_status_url と redirect_url の locals 付きで paypal_service/success を layout: false でレンダリングする。ブラウザの JavaScript が op_status_url を completed: true になるまでポーリングし、その後 redirect_url（success_processed エンドポイント）にリダイレクトする。
優先度の根拠	すべての非同期 PayPal トランザクションに必要な中間ステップ；これがなければトランザクション作成がファイナライズされない。
単独での確認方法	PayPal チェックアウトを完了 → スピナーページが表示され、数秒以内に確認に自動リダイレクトされることを確認する。

受け入れシナリオ:

1. 前提 購入者が有効なトークンで PayPal から戻った場合、操作 success が発火すると、結果 op_status_url 付きのポーリングスピナーがレンダリングされ、JS が完了までポーリングした後リダイレクトする。
2. 前提 paypal_payments_service.create が失敗した場合、操作 購入者が戻ると、結果 汎用エラーをフラッシュ表示し検索にリダイレクト。
3. 前提 コミュニティが PayPal 未対応の場合、操作 いずれかのチェックアウトエンドポイントにアクセスすると、結果 HTTP 400 が返される。

対応する要件	FR-001 (PayPal 操作ステータスをポーリング), FR-002 (PayPal 成功リターンを処理)
適用する業務ルール	BR-001_CommunityPayPalReadiness, BR-002_PayPalTokenRequired
状態遷移	SM-001 polling → completed → redirecting
検証シナリオ	SC-001

US069_ViewPayPalSuccess — PayPal 決済成功ページの表示 （優先度: P2）

処理の流れ	ポーリング完了後、ブラウザは success_processed_path にリダイレクトされる。#success_processed はファイナライズされたプロセスステータスを取得し、handle_proc_result を呼び出し、成功時は transaction_created_path にリダイレクトするか、エラーコード固有のパスにディスパッチする。
優先度の根拠	PayPal 決済確認の最終ステップ；これがなければトランザクションが停滞して見える。
単独での確認方法	PayPal 認可とポーリング後、ユーザーがトランザクション確認ページに着地することを確認する。

受け入れシナリオ:

1. 前提 プロセスが正常に完了した場合、操作 success_processed が発火すると、結果 トランザクション確認にリダイレクト。
2. 前提 PayPal エラーコード 10486 の場合、結果 PayPal リトライ URL にリダイレクト。
3. 前提 PayPal エラーコード 13113 の場合、結果 「購入者が支払いできません」エラーをフラッシュ表示しリスティングにリダイレクト。

対応する要件	FR-005 (処理済みトランザクションをファイナライズ)
適用する業務ルール	BR-003_ProcessTokenMustComplete
検証シナリオ	SC-003

US070_ViewPayPalCancelled — PayPal 決済キャンセルページの表示 （優先度: P2）

処理の流れ	購入者が PayPal で「キャンセル」をクリックすると、cancel URL に戻る。#cancel が paypal_payments_service.request_cancel を呼び出して保留中の決済を無効化する。成功時、「決済がキャンセルされました」フラッシュが表示され、購入者はリスティングページにリダイレクトされる。
優先度の根拠	PayPal 上の孤立した決済認可を防止する；購入者にクリーンな終了を提供する。
単独での確認方法	PayPal チェックアウトの途中でキャンセル → 購入者が「決済がキャンセルされました」通知付きでリスティングページに着地することを確認する。

受け入れシナリオ:

1. 前提 購入者が PayPal でキャンセルした場合、操作 キャンセル URL が発火すると、結果 PayPal トークンがキャンセルされ「決済が正常にキャンセルされました」通知付きでリスティングにリダイレクト。
2. 前提 キャンセルリクエストが失敗した場合、結果 エラーをフラッシュ表示し検索にリダイレクト。

対応する要件	FR-003 (PayPal キャンセルリターンを処理)
適用する業務ルール	BR-001_CommunityPayPalReadiness
検証シナリオ	SC-002

US100_RequestPayPalOrderPermission — PayPal 注文パーミッションのリクエスト （優先度: P2）

処理の流れ	ユーザーが ask_order_permission にアクセスする。コミュニティの準備状況がチェックされる。accounts_api.request が呼び出され、PayPal パーミッションリダイレクト URL を取得する。成功時、クライアントに JSON {redirect_url} を返す（JS がユーザーを PayPal パーミッションページにリダイレクト）。リターン時、permissions_verified コールバックがアカウント作成を完了する。
優先度の根拠	PayPal 売り手アカウント設定の最初のステップ — 請求同意をリクエストする前に完了する必要がある。
単独での確認方法	売り手として決済設定を訪問し、PayPal 接続を開始 → PayPal パーミッションページへのリダイレクトを確認する。

受け入れシナリオ:

1. 前提 コミュニティが PayPal 対応済みの場合、操作 販売者が ask_order_permission にアクセスすると、結果 リダイレクト URL が JSON として返され、クライアントが PayPal にリダイレクトする。
2. 前提 PayPal API からのリダイレクト URL が空白の場合、結果 「リダイレクト URL を取得できませんでした」をフラッシュ表示し決済設定にリダイレクト。

対応する要件	FR-006 (PayPal 注文パーミッションを開始)
適用する業務ルール	BR-005_PayPalCommunityReadyForPermissions
検証シナリオ	SC-006

US101_RequestPayPalBillingAgreement — PayPal 請求同意のリクエスト （優先度: P2）

処理の流れ	ユーザーが ask_billing_agreement にアクセスする。注文パーミッションステートがチェックされ、:verified でなければならない。検証済みの場合、accounts_api.billing_agreement_request が呼び出され、請求同意リダイレクト URL を取得する。JSON {redirect_url} を返す。リターン時、billing_agreement_success が請求同意レコードを作成する。
優先度の根拠	PayPal 売り手設定の2番目のステップ — 定期的/事前承認された支払い機能に必要。
単独での確認方法	注文パーミッション検証後、請求同意を開始 → PayPal 請求同意ページへのリダイレクトを確認する。

受け入れシナリオ:

1. 前提 注文パーミッションが検証済みの場合、操作 販売者が ask_billing_agreement にアクセスすると、結果 リダイレクト URL が返され、クライアントが PayPal にリダイレクトする。
2. 前提 注文パーミッションが未検証の場合、結果 ask_order_permission にリダイレクトし前のステップを完了させる。
3. 前提 請求同意 URL が空白の場合、結果 「リダイレクト URL を取得できませんでした」をフラッシュ表示し決済設定にリダイレクト。

対応する要件	FR-007 (PayPal 請求同意を開始)
適用する業務ルール	BR-004_PayPalOrderPermissionPrerequisite, BR-005_PayPalCommunityReadyForPermissions
検証シナリオ	SC-005

例外・境界条件

条件	期待する動作
token パラメータなしで PayPal 成功 URL にアクセス	エラー/not-found ページにリダイレクト。「お探しのページは存在しません。」
購入者が PayPal から戻った時にコミュニティの PayPal が未設定	HTTP 400 が返される。リダイレクトなし。なし（400 のボディは空白）
PayPal エラーコード 10486（資金不足/アカウント間違い）	レスポンスデータからの PayPal リトライ URL にリダイレクト。なし — PayPal がメッセージを処理する
PayPal エラーコード 10425（販売者の Express Checkout が無効）	エラー付きでリスティングにリダイレクト。メッセージは allow_free_conversations? により変化
PayPal でユーザーが請求同意をキャンセル	billing_agreement_cancel が同意を無効化し決済設定にリダイレクト。「請求同意がキャンセルされました。」
PayPal アカウント制限（エラーコード 520009）	「アカウント制限」メッセージ付きで flash_error_and_redirect_to_settings。「お使いの PayPal アカウントは制限されています。」

主要データ

データ名	テーブル	主な列	画面の目的
Transaction	transactions	id, current_state, payment_gateway, community_id, listing_id	PayPal 非同期フローで追跡されるコアトランザクション
PaypalPayment	paypal_payments	id, transaction_id	トランザクションに紐づく PayPal 固有の決済レコード
Community	communities	id, country	PayPal 手数料 URL とロケールに使用される国コード
Person	people	id	PayPal アカウントを設定する販売者

関連成果物

成果物	ファイル	参照コード	レビュー状況
システム概要	system-overview.md	—	確認済み
ルート一覧	docs/generated/route-list.md	—	確認済み
機能一覧	feature-list.md	F020	確認済み
画面遷移	docs/generated/screen-flow.md	—	確認済み
利用者視点の要件	user-stories.md	US068, US069, US070, US100, US101	確認済み
画面一覧	screen-list.md	SCR095, SCR096, SCR097, SCR098, SCR099, SCR100, SCR101	確認済み
バックグラウンドロジック	docs/generated/behavior-logic.md	—	確認済み
エンティティ	data-model.md	DISC-011, DISC-012	確認済み
権限マトリクス	permissions-matrix.md	—	確認済み

前提条件

• paypal_service/success ビューテンプレートには、op_status_url を定期的に呼び出すクライアントサイドのポーリング JavaScript が含まれている。このテンプレートは読み取っていないが、JS ポーリングロジックはコントローラーから渡される locals に基づいて推定している。
• SCR098_TransactionOpStatus と SCR099_FinalizeProcessed は TransactionsController#transaction_op_status と #finalize_processed に対応する — これらは PayPal フローと同じスピナーテンプレートを共有するが、ゲートウェイ非依存（Stripe 非同期フローでも使用される）。
• PaypalHelper.community_ready_for_payments? は保存されたコミュニティ PayPal 設定に対する同期チェックであり、before_action 中に外部 API コールは行われない。

根拠となるソースコード

処理名	ファイル	画面の目的
CheckoutOrdersController#success	paypal_service/checkout_orders_controller.rb:11-38	PayPal リターンハンドラー＋非同期スピナーレンダリング
CheckoutOrdersController#success_processed	paypal_service/checkout_orders_controller.rb:41-51	ポーリング後のファイナライズ＋エラーコードディスパッチ
CheckoutOrdersController#cancel	paypal_service/checkout_orders_controller.rb:53-61	キャンセルトークン無効化＋リダイレクト
CheckoutOrdersController#paypal_op_status	paypal_service/checkout_orders_controller.rb:64-76	JSON ポーリングエンドポイント
PaypalAccountsController#ask_order_permission	paypal_accounts_controller.rb:14-36	販売者パーミッション開始
PaypalAccountsController#ask_billing_agreement	paypal_accounts_controller.rb:38-73	販売者請求同意開始
TransactionsController#transaction_op_status	transactions_controller.rb:208-225	汎用（非 PayPal）操作ステータスポーリング
TransactionsController#finalize_processed	transactions_controller.rb:197-206	非同期完了後の汎用ファイナライズ

追加確認が必要な事項

ポーリング間隔	paypal_service/success のクライアントサイド JS ポーリング間隔は読み取っていない — 固定間隔なのか指数バックオフなのか不明。
SCR098 vs SCR095	両方とも操作ステータスのスピナーを表示するが、一方は PayPal 固有、もう一方は汎用。それぞれが表示される正確な条件の確認が必要。
請求同意の必要性	請求同意がすべての PayPal 事前認証トランザクションに必要なのか、定期的なもののみなのかはコードから確認されていない。

画面仕様 — F020_TransactionPayPalFlow

画面一覧

画面名	表示内容	可能な操作
PayPal Operation Status	PayPal 決済が非同期で処理されている間、進捗インジケーター付きのスピナー/ローディングページが表示される	待機 — 処理完了時にページが自動リダイレクトされる。手動操作は不要
PayPal Payment Success	PayPal 認証後、最終的なトランザクションレコードが確認されるまで表示される短い中間ページ（同じスピナーテンプレート）	待機 — トランザクション確認画面に自動リダイレクト
PayPal Payment Cancelled	購入者が PayPal でキャンセルした後のリダイレクト先。表示ページなし（リスティングへの即時リダイレクト）	なし — 「決済がキャンセルされました」通知付きの自動リダイレクト
Transaction Operation Status	非同期トランザクション操作用の汎用スピナーページ（PayPal 固有ではない）	待機 — 操作完了時に自動リダイレクト
Finalize Processed Transaction	非同期プロセストークンの完了を確認する中間リダイレクトページ	なし — トランザクション詳細またはエラーページへの即時リダイレクト
PayPal Permissions Initiation	販売者アカウント設定ステップ 1 — リダイレクト URL を返す。表示ページなし（クライアントへの JSON レスポンス）	なし — PayPal パーミッションページへの自動リダイレクト
PayPal Billing Agreement Request	販売者アカウント設定ステップ 2 — リダイレクト URL を返す。表示ページなし（クライアントへの JSON レスポンス）	なし — PayPal 請求同意ページへの自動リダイレクト

操作の流れ

購入者 — PayPal 決済の完了

1. 購入者が Preauthorize Checkout スクリーンでチェックアウトフォームを送信し、PayPal のウェブサイトにリダイレクトされる。
2. 購入者が PayPal にログインし、支払いを承認する。
3. 購入者がマーケットプレイスに戻り、トランザクションが記録されている間 PayPal Operation Status スピナーが表示される。
4. スピナーが PayPal Payment Success 画面に自動リダイレクトし、そこからトランザクション確認ページに即座にリダイレクトされる。
5. 購入者は完了した予約を表示する Transaction Detail ページに到着する。

購入者 — PayPal 決済のキャンセル

1. 購入者が PayPal 認証ページで「キャンセル」をクリックする。
2. 購入者がマーケットプレイスに戻り、PayPal Payment Cancelled が発火してリスティングページに即座にリダイレクトされる。
3. 購入者はリスティングページで「決済が正常にキャンセルされました」という通知を確認する。

販売者 — PayPal の設定

1. 販売者が決済設定にアクセスし、「PayPal を接続」をクリックする。
2. 販売者が PayPal にリダイレクトされ、注文処理パーミッションを付与する（PayPal Permissions Initiation）。
3. パーミッション付与後、販売者はマーケットプレイスに戻り、請求同意ステップの完了を求められる。
4. 販売者が再び PayPal にリダイレクトされ、請求同意を承認する（PayPal Billing Agreement Request）。
5. 承認後、販売者は PayPal アカウントが完全に接続された状態で決済設定に戻る。

例外・境界条件 — F020_TransactionPayPalFlow

発生条件	システムの動作	利用者への表示
token パラメータなしで PayPal 成功 URL にアクセス	エラー/not-found ページにリダイレクト	「お探しのページは存在しません。」
購入者が戻った時にコミュニティの PayPal 設定が設定されていない	before-action が空のボディで HTTP 400 を返す。リダイレクトなし	なし（空の 400 レスポンス）
PayPal エラーコード 10486 — 購入者が間違ったアカウントを使用または残高不足	レスポンスデータに含まれる PayPal リトライ URL にリダイレクト	なし — PayPal が自サイト上でメッセージを処理
PayPal エラーコード 13113 — 購入者のアカウントがこの支払いを行えない	フラッシュエラー。リスティングページにリダイレクト	「購入者の PayPal アカウントではこの支払いを行えません。PayPal カスタマーサービスにお問い合わせください。」
PayPal エラーコード 10417 — トランザクションを完了できない	フラッシュエラー。リスティングページにリダイレクト	「このトランザクションは完了できません。」
PayPal エラーコード 10425 — 売り手が Express Checkout を有効にしていない	フラッシュエラー（文言は allow_free_conversations? により異なる）。リスティングにリダイレクト	「売り手が PayPal Express Checkout を有効にしていません。」
PayPal の payment-review ステータス	フラッシュ警告（エラーではない）。リスティングにリダイレクト	「支払いは PayPal による審査待ちです。」
未処理の PayPal エラーコード	フラッシュ汎用エラー。サーバー側で警告がログ記録。リスティングにリダイレクト	「PayPal で問題が発生しました。もう一度お試しください。」
購入者が PayPal でキャンセルし request_cancel が失敗	フラッシュキャンセルエラー。検索にリダイレクト	「PayPal 支払いのキャンセル中に問題が発生しました。もう一度お試しください。」
finalize_processed 発火時にプロセストークンがまだ完了していない	エラー/not-found ページにリダイレクト	「お探しのページは存在しません。」
売り手が確認済み注文権限なしで ask_billing_agreement にアクセス	ステップ 1 を完了するために ask_order_permission にリダイレクト	なし — 通知せずにリダイレクト
権限または課金契約の PayPal API が空のリダイレクト URL を返す	フラッシュエラー。支払い設定にリダイレクト	「PayPal のリダイレクト URL を取得できませんでした。もう一度お試しください。」
PayPal アカウントにエラーコード 570058（アカウント未認証）	permissions_verified コールバックで固有のフラッシュエラー	「あなたの PayPal アカウントは認証されていません。」
PayPal アカウントにエラーコード 520009（アカウント制限）	コールバックで固有のフラッシュエラー	「あなたの PayPal アカウントは制限されています。」