サンドボックスのテストデータ：シナリオ・マジック値・書類

​

環境モデル

• すべての外部プロバイダー(OCR、AML、顔照合、ライブネス、NFC、電話番号、メールアドレス、IP、POA、データベース検証、Document AI)はモック化され、サードパーティが呼び出されることは一切ありません。
• ライブネスは本番環境とまったく同じように実行されます。 アクティブライブネスのワークフローでは、ホスト型フローでもネイティブSDKのWeb引き継ぎでも、サンドボックス内で実際のアクティブキャプチャが実行されるため、ユーザーが体験する操作をそのままテストできます。シミュレートされるのはライブネスの結果のみで、シナリオまたはマジック値によって決まります。レポートには、ワークフローで設定した方式が記録されます。
• カスタムドメインは本番環境専用です。 サンドボックスのアプリケーションではカスタムドメインを追加できず、サンドボックスのセッションは常にデフォルトのホスト型検証ドメインで実行されます。
• セッションは課金されません。また、残高チェックは行われません。
• アプリケーションごとに24時間あたり500件のセッション作成という上限が適用されます。
• Webhookには"environment": "sandbox"が含まれます(本番環境のセッションには"environment": "live"が含まれます)。
• ホスト型フローはセッションの環境を公開するため、UIでユーザーに実際の個人情報(PII)をアップロードしないよう警告できます。
• 結果がピクセルに左右されることはありません。抽出データとステータスは、シナリオまたはマジック値によって決まります。撮影されたメディア自体(書類、セルフィー、動画、POAファイル)は、本番環境のセッションとまったく同じように実際に保存されます。

​

サンドボックスでのトランザクションモニタリング

• ルール評価なし。 ルールのモードにかかわらず、rule_runsは空です。サンドボックスアプリケーション上のACTIVEルールは決して発火しないため、取引はスコア0のAPPROVEDのままとなり、アラートもケースも作成されません。
• AML/ウォレットスクリーニングなし。 モニタリングが有効なアプリケーション上の暗号資産取引であっても、provider_resultsは空です。
• Webhookなし。 サンドボックスの取引については、transaction.createdもtransaction.status.updatedも配信されません。
• 課金なし。 利用イベントは料金0.0000で記録され、残高は変わりません。

​

トラベルルールのTest VASPシナリオ

​

本番環境とサンドボックスを切り替える方法

• モックされ、課金されず、シミュレーション可能なセッションを取得するには、サンドボックスモードのアプリケーションのAPIキーを使用します。
• 実際の認証には、本番モードのアプリケーションのAPIキーを使用します。

​

ホスト型検証フローでのサンドボックス

• カード内のサンドボックスバナー。 すべての画面のカード内に「テストデータのみ・実際の呼び出しなし」というバナーが表示されるため、セッションが実際のプロバイダーを呼び出すことも、残高に影響することもないことが常に一目でわかります。撮影されたメディアは通常のセッションと同様に保存されるため、実際の本人確認書類や個人情報ではなく、サンプル書類とテストデータを使用してください。
• フロー開始前のシナリオ選択。 撮影が始まる前に、カード内の選択画面でユーザーがテスト結果を選びます。まず結果を選び、次にその結果のトリガーを選びます。確定するとPOST /v3/session/{session_id}/sandbox/arm/が呼び出され(後述のフロー開始前にセッションをアーム(または再アーム)するを参照)、そのシナリオのマジックバリューが適用された状態でフローに進みます。
• サンプル書類の一覧。 書類のアップロード・撮影コンポーネントのすぐ下に、サンドボックスのサンプル書類(最大3件)が1行で表示されます。いずれかをタップすると、実際のアップロードの代わりにそのサンプルを使用できます。

​

シナリオ

​

マジック値

​

書類以外の照会とIDウォレット

​

銀行口座認証の口座チェック

​

サンプル書類

​

サンプルの本人情報: expected_detailsのテスト

{
  "workflow_id": "<your-workflow-uuid>",
  "expected_details": {
    "date_of_birth": "1990-06-15",
    "gender": "M",
    "nationality": "BRA",
    "identification_number": "YC531181"
  }
}

​

生成された書類に含まれない情報

• セッション作成時にmetadataで州を送信し(例: "metadata": {"credential_state": "IL"})、metadata.credential_stateで分岐します。メタデータはサンドボックスでも本番環境とまったく同じように評価されます。
• 書類で州を証明する必要もある場合は、本番トラフィック用に書類由来のkyc.region条件を残しておきます。本番モードでは、地域は実際の書類から読み取られます。

​

OTPコードとメールのオプトイン

• 電話番号のOTP: サンドボックスの電話番号チェックは、正しい形式のコード(4〜8桁、123456を含む)をすべて受け付けます。不正な形式の入力には引き続き400が返されます。
• メールのOTP: サンドボックスのメールチェックは、正しい形式のコード(123456を含む)をすべて受け付けます。不正な形式の入力には引き続き400が返されます。

​

シナリオ、マジック値、アーム、simulateエンドポイントによる結果の制御

​

1. セッション作成時のsandbox_scenario

{
  "workflow_id": "<your-workflow-uuid>",
  "sandbox_scenario": "decline_document_expired"
}

​

2. 手入力のマジック値

​

3. フロー開始前にセッションをアームまたは再アームする

POST /v3/session/{session_id}/sandbox/arm/
Session-Token: <session_token>

{
  "scenario": "decline_document_expired"
}

{
  "session_id": "<session_id>",
  "scenario": "decline_document_expired",
  "status": "Not Started"
}

• 認証には、アプリケーションのAPIキーではなく、セッション自身のSession-Token(セッション作成時にsession_tokenとして返されます)を使用します。これはクライアント向けのエンドポイントです。
• 不明なシナリオslugの場合は400を返します。セッションがNot Startedより先に進んだ後も400を返します("Scenario can only be armed before the verification starts.")。
• Session-Tokenが本番(サンドボックス以外)のアプリケーションに属する場合、またはパス内のsession_idと一致しない場合は404を返します。
• 再アームすると、以前のシナリオが置き換えられます。 消去されるのは以前のシナリオが書き込んだマジック値だけです。ユーザーがすでに手入力した内容(メールアドレス、名など)はそのまま残ります。たとえば、decline_phone_high_riskをアームしてからapproveをアームすると、電話番号は未設定に戻ります。一方、顧客が入力したメールアドレスは両方の呼び出し後も残ります。

​

4. simulateエンドポイント

• コンソール / APIキー(write:sessions権限が必要です。スコープ付きAPIキーにはセッションへの書き込み権限が必要です): POST /v3/session/{session_id}/simulate/
• ホスト型フロー(Session-Tokenヘッダー): POST /v3/session/{session_id}/sandbox/simulate/

{
  "scenario": "decline_aml_hit",
  "send_webhooks": false
}

{
  "session_id": "<session_id>",
  "previous_status": "In Progress",
  "status": "Declined",
  "scenario": "decline_aml_hit",
  "risk": "POSSIBLE_MATCH_FOUND",
  "send_webhooks": false
}

• statusはシミュレーションで設定されたステータス、previous_statusはそれ以前のセッションのステータスです。
• scenarioは指定したslugをそのまま返し、riskは適用されたリスクケースです。該当がない場合はそれぞれnullになります。
• send_webhooksは適用された値をそのまま返します。
• 次の場合は400を返します。不明なシナリオまたはリスクの場合、new_statusを導出できない場合、上記以外のnew_statusの場合、セッションがすでに要求されたステータスにある場合(["The new status is the same as the current status."])です。

​

5. スタンドアロンAML APIでのsandbox_scenario

{
  "full_name": "Ada Lovelace",
  "save_api_request": true,
  "sandbox_scenario": "decline_aml_hit"
}

• decline_aml_hitは本番環境と同じ形式のヒットを1件返し、スクリーニングをDeclinedで確定します。review_aml_possible_matchはIn Reviewで確定します。AML結果を設定しないシナリオでは、スクリーニングはヒットなしになります。
• save_api_request: true(デフォルト)の場合、スクリーニングは本番のキーとまったく同じように保存されます。そのため、返されたrequest_idはGET /v3/session/{request_id}/decision/とGET /v3/session/{request_id}/generate-pdf/で参照できます。
• 不明なシナリオslugの場合は400を返します。APIキーが本番のアプリケーションに属する場合も400を返します。

​

sandbox_scenarioが表示される場所

​

利用状況と請求

• モックされた呼び出しでも利用イベント（is_sandbox: true、料金0.0000）は必ず記録されるため、デバッグ時にサンドボックスの利用量を確認できます。ただし、この利用量が利用合計に加算されることも、残高から差し引かれることも、請求書に記載されることもありません。
• Business Consoleの残高、チャージ、本番利用状況の画面では、デフォルトでサンドボックスの利用状況が除外されます。チャージ利用状況のエンドポイントはenvironmentパラメーター（デフォルトのlive、またはsandbox）を受け付けるため、サンドボックスの利用量を個別に確認できます。この場合も費用は常にゼロで、無料枠は消費されません。
• メールアドレス認証と電話番号検証は、セッションの結果ごとではなくリクエストごとに課金されますが、サンドボックスにはWebhookレイヤーでこれを完全に再現する方法がありません。サンドボックスのメール・電話番号チェックでも、他のすべてのモック機能と同様に、リクエストごとに料金0.0000の利用イベントが記録されます。これは本番環境の課金動作との既知かつ許容された相違であり、バグではありません。
• サンドボックスにおけるデータベース検証のレスポンス形式は、再現すべき実際のプロバイダーが存在しないため、本番環境のプロバイダーごとの形式とは意図的に異なります。サンドボックスのデータベース検証のペイロードは結果（ステータスと警告コード）の代替として扱い、本番環境のプロバイダーレスポンスをバイト単位で正確に再現したプレビューとはみなさないでください。