> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# サンドボックスのシミュレーション範囲 FAQ

> Waffo のサンドボックスで再現できること・できないこと：どの予約金額がどのエラーを発生させるか、返金用の金額が機能しない理由、ウォレット側のキャンセルをシミュレートする方法、シミュレートした更新失敗が再試行されない理由、そしてサンドボックスにまったく経路のないシナリオ。

サンドボックスへのアクセス方法と、セットアップウィザードが何を変えるかは
[サンドボックス環境とアクセス FAQ](/docs/ja/support/sandbox-environment-and-access-faq) にあります。
シミュレーターの操作手順は
[サンドボックスシミュレーター](/docs/ja/developer-docs/tools-and-references/developer-tools/sandbox-simulator) と
[サンドボックステスト FAQ](/docs/ja/support/sandbox-testing-faq) にあります。

**このページは境界線の地図です。** サンドボックスが実際に生成できるシナリオ、できないシナリオ、そして予約金額が
適用される場所とされない場所を示します。受け入れテストを計画する前に読んでください。サンドボックスに経路のないものを
再現しようとして 1 日を費やさずに済みます。

## 何をシミュレートでき、何ができないのか、全体の一覧をください。

| シナリオ | サンドボックスで利用可能か |
| - | - |
| 決済成功 | はい — チェックアウトページのシミュレーションボタン |
| 決済失敗 / 拒否 | はい — チェックアウトページのシミュレーションボタン |
| チャネル拒否（`C0005`） | はい — 予約された注文金額 |
| システムエラー（`C0001`） | はい — 予約金額。作成時とキャンセル時 |
| 不明なステータス（`E0001`） | はい — 予約金額。作成時とキャンセル時 |
| 冪等性の競合（`A0011`） | はい — 同じリクエスト ID を異なる金額または通貨で再利用する |
| 元の金額を超える返金（`A0003`） | はい — 支払われた金額より多く要求する |
| 決済前の注文キャンセル | はい — キャンセル API |
| サブスクリプション初回課金の成功と失敗 | はい — チェックアウトページ |
| サブスクリプションの更新、成功または失敗 | はい — サブスクリプション管理ページ |
| ウォレット側（顧客起点）のキャンセル | はい、対応する決済手段について — 下記参照 |
| 返金の失敗 | はい、同期的に — 返金リクエストに作成系の予約金額を指定するとエラーが返り、`REFUND_FAILED` の返金注文が残ります。下記参照 |
| 最初は処理中になり、その後失敗する返金 | **いいえ** — シミュレーションの経路なし |
| チャージバック / 異議申し立て | **いいえ** — シミュレーションの経路なし |
| チャネルのタイムアウトまたは無応答 | **いいえ** — 直接的にはできません。`E0001` が最も近い類似物です |
| Payout、出金、精算の結果 | **いいえ** — API は存在しますが、結果を強制する手段がありません |
| タイムトラベル（トライアル終了日や有効期限を進める） | **いいえ** — そのような機能は存在しません |
| 3DS チャレンジ | **いいえ** — チャレンジを強制する手段はなく、テストカード一覧にも 3DS 用のカードはありません |

「いいえ」の行はすべて、文書化されていないだけではなく本当に存在しません。それを前提に計画してください。それらのコード経路は
記録済みペイロードに対するユニットテストで検証し、実際の動作は本番稼働後に本番環境で確認してください。

## どの予約金額がどのエラーを発生させ、どのエンドポイントに適用されますか？

サンドボックスは特定の注文金額を横取りし、通常処理の代わりに対応するエラーを返します。対応表：

| 予約金額 | 返されるエラー | 適用対象 |
| - | - | - |
| `90`、`990`、`1990`、`19990` | `C0005` Payment Channel Rejection | 注文作成、サブスクリプション作成 |
| `9.1`、`91`、`991`、`1991`、`19991` | `C0001` System Error | 注文作成、サブスクリプション作成 |
| `9.2`、`92`、`992`、`1992`、`19992` | `E0001` Unknown Status | 注文作成、サブスクリプション作成 |
| `9.3`、`93`、`993`、`1993`、`19993` | `C0001` System Error | 注文キャンセル、サブスクリプションキャンセル |
| `9.4`、`94`、`994`、`1994`、`19994` | `E0001` Unknown Status | 注文キャンセル、サブスクリプションキャンセル |

「適用対象」の列を注意して読んでください。ここで間違いが起きます。

* **作成**時は、金額はリクエストから取られます。注文作成なら注文金額、サブスクリプション作成ならその金額です。
* **キャンセル**時は、金額を渡しません。照合されるのは**キャンセル対象の注文またはサブスクリプションに保存されている**
  金額です。そのため、キャンセルのエラーをテストするには、まず `9.3` で注文を作成し、その後キャンセルする必要があります。
* これらの金額は**サンドボックス限定のルール**です。本番環境にこれに相当するものはなく、同じ金額は通常の金額です。

## 返金用の予約金額が機能しないのはなぜですか？

返金の経路が返金専用の金額を使用していないためです。公開されている
[サンドボックスシミュレーター](/docs/ja/developer-docs/tools-and-references/developer-tools/sandbox-simulator)
のページで返金 API 向けに記載されている `9.5` と `9.6` の系列は、**有効になりません** — `995` の返金は通常の返金です。

返金の経路が実際に反応するのは**作成**系の金額です。`refundAmount` が `90` / `9.1` / `9.2` の系列の値（注文作成で
`C0005`、`C0001`、`E0001` を発生させるのと同じ金額）と一致すると、返金リクエストはリクエスト時点で対応するクラスの
エラーで失敗します。`90` と `9.1` の系列ではチャネルエラーまたはシステムエラー、`9.2` の系列では不明ステータスのエラーです。
そのリクエストのために開かれた返金注文は `REFUND_FAILED` で終了し、失敗を報告する返金通知が返金通知 URL に送信されます。
これにより、拒否された返金リクエストと失敗した返金レコードの処理を検証できます。できないのは、最初に処理中となり後から
失敗する返金であり、サンドボックスでそれを強制する他の方法はありません。返金の経路で*引き続き*検証できること：

| 返金のケース | 方法 |
| - | - |
| 返金の成功（全額および一部） | 支払い済みのサンドボックス注文を返金する |
| 元の金額を超える返金 → `A0003` | 支払われた金額より多く要求する |
| 返金の冪等性の競合 → `A0011` | `refundRequestId` を異なる金額または通貨で再利用する |
| 返金通知の処理 | 上記のケース（同期的な失敗を含む）で返金通知が発火する |

本当の返金*失敗*については、無理に発生させようとするのではなく、記録済みペイロードに対してハンドラーをテストしてください。

## 実際の価格が予約金額に当たってしまい、サンドボックスの注文が失敗し続けます

これは既知の状況で、対処法は「価格を変える」ことではありません。**サンドボックスの加盟店 ID を金額シミュレーションの
対象外にできます。** サンドボックスの加盟店 ID を添えて連携サポートに除外を依頼してください。適用されると、
そのサンドボックスでは予約金額が通常の金額として扱われます。

それまでの回避策は、上記の 5 系列を避けることです。実務的には、`90` で終わる金額と、`9.x` / `x91`〜`x96` のパターンを
避けることを意味します。照合は完全一致であるため、1 セント加える（たとえば `90` ではなく `90.01`）だけで十分です。

## サンドボックスは本当に Webhook を送信しますか？

はい。サンドボックスの Webhook 配信は本番と同じ契約に従います。同じ署名、同じ受理レスポンスボディ、同じ再試行スケジュールです。
[Webhook 配信契約 FAQ](/docs/ja/support/webhook-delivery-contract-faq) の内容がそのまま適用されます。

違いではないのに、違って見えるとして責められがちな 2 点：

* **`notifyUrl` はパブリックに到達可能である必要があります。** サンドボックスは `localhost` やプライベートアドレスに
  到達できず、TLS 証明書もパブリックに信頼されている必要があります。ローカル開発ではトンネリングツールを使用してください。
* **サンドボックスが遅いように見えるのは、たいてい再試行スケジュールです。** 最初の配信が失敗すると、以降の試行は
  増加するバックオフに従います。スケジュールは
  [Webhook の再試行](/docs/ja/developer-docs/webhook/retry) を参照してください。
  「届くのに数分かかった」通知は、ほぼ必ず最初の試行が拒否されたことを意味します。サンドボックスが遅いと結論づける前に、
  Portal の Webhook ログで同じレコードの以前の失敗した試行を確認してください。

## どのテストカード番号を使えばよいですか？

カードの入力を求められるフローでは、**サンドボックスのチェックアウトページのクイック入力ボタン**を使用してください。
サンドボックスで有効になっているカードブランドごとに、成功または拒否用のカード番号、有効期限、CVV をワンクリックで
入力します。これにより、転記ミスと、その環境がどの値を期待しているかという推測の両方がなくなります。

値を書き留めておきたい場合、Portal の一覧が **Merchant Portal → Integration → Test Cards** にあり、カードごとのコピー操作と、
**successful** と **failed** の 2 つのシナリオカテゴリーがあります。

[サンドボックステスト FAQ](/docs/ja/support/sandbox-testing-faq) の表は Portal の一覧と一致しています。古い公開版の
シミュレーターページは一部のスキームで一致していないため、**どのドキュメントよりもプロダクト内の情報源を優先し**、
その両方よりチェックアウトのクイック入力を優先してください。

## 有効期限と CVV には何を入力しますか？ 検証されますか？

任意の未来の有効期限と、正しい桁数の任意の CVV（3 桁、4 桁を使うスキームでは 4 桁）です。チェックアウトページの
クイック入力が有効な組み合わせを用意してくれます。

これがカバレッジについて示すこと：有効期限と CVV が実質的に検証されないため、サンドボックスでは有効期限切れによる拒否や
CVV 不一致の処理を検証できません。それらは「記録済みペイロードでテストする」リストに属します。

## Portal のテストカードページには成功と失敗しかありません。3DS、残高不足、CVC エラー、リスク拒否のカードはどこですか？

存在しません。Portal のテストカード一覧にはちょうど 2 つのシナリオカテゴリー（successful と failed）しかなく、
特定の拒否理由に対応するカード番号はありません。

受け入れテスト計画への影響：サンドボックスは、成功と失敗でコードが正しい分岐を取ることを証明します。拒否理由を
列挙させることはできません。拒否理由ごとに挙動が異なるプロダクト（残高不足なら再試行を促し、ハード拒否なら「別のカードを
使ってください」と促すなど）では、
[エラーコード](/docs/ja/developer-docs/tools-and-references/developer-tools/error-codes) のコードを使って、
ユニットテストで `orderFailedReason` から分岐を動かしてください。

## 更新はどのようにシミュレートしますか？ 期間を連続させられますか？

サブスクリプション管理ページから行います。`POST /api/v1/subscription/manage` を呼び出し、返された `managementUrl` を
開いてアクセスします。次回決済の成功シミュレーションと失敗シミュレーションが用意されており、クリックごとに 1 期間進むため、
連続実行できます。期間 2 は成功、期間 3 は失敗、といった具合です。

ボタンが表示されない原因になる前提条件：

| 要件 | 満たさないとボタンが表示されない理由 |
| - | - |
| サブスクリプションが `ACTIVE` である | それ以外のステータスではシミュレーションが拒否されます |
| サブスクリプションが Waffo 管理の課金スケジュールである | 決済手段側から課金が駆動されるサブスクリプションは、別の経路でシミュレートされます |
| サンドボックスにいる | 本番ではシミュレーションのエントリーポイントは何もしません |

ページは表示されるのにシミュレーションのコントロールがない場合は、まずサブスクリプションのステータスを確認してください。
未有効化またはすでにキャンセル済みのサブスクリプションが圧倒的に多い原因です。

## シミュレートした失敗期間は、その後通常のスケジュールで再試行されますか？

**いいえ。これがこのページで最も重要な点です。** 更新の失敗をシミュレートすると、**まず更新の再試行回数がゼロに設定される**
ため、失敗した期間は再試行スケジュールに入らず、そのまま終了状態へ進みます。

計画すべき 2 つの結果：

* **失敗をシミュレートしても、サンドボックスで更新の再試行動作を観察することはできません。** 本番で動く再試行スケジュールは、
  シミュレーション自体によってバイパスされます。
* **この変更はそのサンドボックスのサブスクリプションの設定に残り続けます。** その後も更新の再試行は無効のままであるため、
  失敗をシミュレートしたサブスクリプションは、再試行のテスト対象としてはもうきれいではありません。再試行に関するものは
  新しいサブスクリプションを作成してください。

再試行シーケンスを使い切った*結果*の処理をテストするには、シミュレートした失敗がまさに適切です。同じ終了状態の期間と
同じ通知を生成します。シーケンス自体をテストするには、本番の動作か、記録済みのペイロード一式が必要です。

## 顧客がウォレットアプリ内でキャンセルする操作をシミュレートできますか？

はい。対応している決済手段については可能です。このシミュレーションは、実際の顧客側のキャンセルと同じ
`USER_CANCELLED` の `SUBSCRIPTION_STATUS_NOTIFICATION` を生成するため、ハンドラーは本物と同じものを受け取ります。

特定のサブスクリプションで機能するかどうかを決める 2 つの条件：

1. **サブスクリプションが `ACTIVE` であること。**
2. **決済手段がサポートしていること。** ウォレット側のキャンセルは、その決済手段がキャンセル時に実際に送るメッセージを
   再現することでシミュレートされるため、そのメッセージがモデル化されている決済手段でのみ存在します。そうでない場合、
   呼び出しは黙って何もしないのではなく、専用の「この決済手段はチャネルキャンセルに対応していない」エラーで失敗します。
   これ自体が、その決済手段が対応しているかどうかの答えになります。試してエラーを読んでください。

対応していない決済手段の場合は、`USER_CANCELLED` のペイロードに対して直接ハンドラーをテストしてください。通知の形式は
決済手段によって変わりません。

## サンドボックスでチャージバックをテストできますか？

いいえ。サンドボックスにはチャージバックや異議申し立てのシミュレーションはありません。予約金額もボタンもエンドポイントも
ありません。

代わりに行うこと：

| 目的 | 方法 |
| - | - |
| チャージバックの Webhook ハンドラーを検証する | 記録済みの `CHARGEBACK_NOTIFICATION` ペイロードでテストする。フィールド一覧は [Webhook ペイロードのフィールド FAQ](/docs/ja/support/webhook-payload-field-faq) にあります |
| 証拠提出のフローを検証する | [チャージバックのフィールドリファレンス](/docs/ja/support/chargeback-field-reference) の API 契約をたどる |
| 本番で何が起きるかを理解する | [チャージバック FAQ](/docs/ja/support/chargeback-faq) と [チャージバック証拠ガイド](/docs/ja/support/chargeback-evidence-guide) |

計画を立てる前に知っておくべきこと：チャージバック通知は Portal で Chargeback Notify URL が設定されている場合にのみ配信され、
Portal での設定のみです。リクエストパラメーターはありません。したがって最初に確認すべきは、両方の環境でその URL が
設定されているかどうかです。

## 注文が不明な状態のままです。最終結果へ進めるにはどうすればよいですか？

`E0001` は予約金額によって作成時に返され、リクエストは**注文が作成される前に**拒否されます。そのリクエスト ID で照会すると
「注文が存在しない」と返ります。それが要点です。不明ステータスのレスポンスは注文が存在するかどうかについて何も語らないため、
検証すべき動作は復旧ロジックです — **結果を未確定として扱い、照会し、照会が返したものに従って行動してください。
自分で注文を失敗とマークしたり閉じたりしないでください。** 照会で何も存在しないと確認できたら、同一のパラメーターで
再送信してください（`paymentRequestId` によってそれが安全になります）。

注文を作成したうえで不明な状態にとどめ、後から最終結果に変わるようなサンドボックスの制御はありません。したがって
実証すべき動作は、手作業で作った最終状態ではなく、「照会してから判断する」ループと「自分で閉じない」という性質です。
受け入れ基準はこれを次のように表現しています。注文を閉じず、同一のパラメーターで再試行し、照会結果または通知を待つこと。
[連携の受け入れ基準](/docs/ja/developer-docs/tools-and-references/references/acceptance-criteria) を参照してください。

## テストには特定の国からのネットワーク出口が必要ですか？

サンドボックスでは不要です。サンドボックスの決済経路には、リクエストやブラウザーの発信元を確認する処理はなく、
サンドボックスは実際の決済チャネルに接続しないため、チャネル側の地理的制限を満たす必要もありません。どこから実行しても
有効なサンドボックスの実行です。

地理が問題になるのは、顧客の地域に本当に依存する決済手段の本番検証です。モバイルウォレット製品のデバイスやアカウントの
地域設定と、それらの製品が公開する対応国の一覧です。これらのチェックは
[サンドボックスとテスト](/docs/ja/developer-docs/getting-started/sandbox) の決済手段ごとのセクションに記載されており、
サンドボックスではなく本番のチェックです。

## 本番でしか検証できないものは何ですか？

この一覧は本番移行計画の隣に置いておいてください。どの項目も、サンドボックスの実行が成功しても何も証明しない領域です。

| 本番でしか検証できないもの | 理由 |
| - | - |
| 実際の決済手段の動作とその画面 | サンドボックスが表示するのはシミュレーターであり、実際の決済ページではありません |
| 拒否理由とその分布 | サンドボックスには成功と失敗しかありません |
| 更新の再試行動作 | 失敗のシミュレーションが再試行を無効にします |
| 返金の失敗、チャージバック | サンドボックスに経路がありません |
| Payout、出金、精算の結果 | サンドボックスに結果を制御する手段がありません |
| モバイルウォレットのデバイス、アカウント、地域の要件 | 実際のデバイスとアカウントに依存します |
| モバイルウォレット製品の本番アクセス承認 | Waffo ではなくウォレット提供者が付与します |
| 本番の認証情報、ホスト、コールバック URL | 設計上、サンドボックスとは異なる値です |

特にモバイルウォレットのチェックには独自の前提条件の一覧があります。アカウント、カード、デバイスの地域、アプリ内ブラウザーの
設定、そしてローンチ前に承認が必要な本番アクセス申請です。切り替え時に初めて気づくのではなく、
[サンドボックスとテスト](/docs/ja/developer-docs/getting-started/sandbox) と
[決済手段の連携に関する注意事項](/docs/ja/developer-docs/tools-and-references/references/payment-method-integration-notes)
を順に確認してください。

## 契約しているすべての決済手段を個別にテストする必要がありますか？

いいえ。受け入れ基準は網羅的なカバレッジではなく代表的なカバレッジを定めています。カードを少なくとも 1 つ、国ごと・タイプごとに
少なくとも 1 つ、バーチャル口座を少なくとも 1 つ、特別な必須パラメーターを持つ決済手段はすべて、そしてモバイルウォレットは
実機での手動テストです。完全なルールは
[連携の受け入れ基準](/docs/ja/developer-docs/tools-and-references/references/acceptance-criteria) にあります。

頻繁に出てくる 2 つの補足：

* **契約上返金が許可されていない決済手段**には、返金のケースは不要です。条件付きのケースは、連携が実際に含む API と
  動作についてのみ実行してください。テンプレートがそれらを条件付きとして示しているのはそのためです。
* **2 回目の連携は全面的なやり直しではありません。** 一度受け入れに合格していれば、その後のワンタイム決済の連携には
  差分のみをカバーする追加連携用テンプレートを使用します。最初の連携では常に標準テンプレートを使用します。

***

次へ：切り替えそのものについては [本番移行チェックリスト](/docs/ja/developer-docs/getting-started/go-live)、
サンドボックスから何が引き継がれ何が引き継がれないかは
[サンドボックス環境とアクセス FAQ](/docs/ja/support/sandbox-environment-and-access-faq) を参照してください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.