クレジットを消費せずsandboxでテストする
sandboxはアプリケーションごとのモードで、すべてのプロバイダーがモック化され、何も課金されず、必要な検証結果を承認・拒否・審査中のいずれにでも強制できます。
sandboxは本番アプリケーション内の切り替えスイッチではなく、アプリケーションに設定するモードです。sandboxモードの2つ目のアプリケーションを作成し、そのAPIキーを使うと、すべてのチェックがモック化され、何も課金されず、望む結果を自由に強制できます。本番用のアプリケーションしか見当たらない場合は、sandbox用のアプリケーションを作成する必要があります。モードはアプリケーションごとに選択します。
Diditのsandboxは、決済プロバイダーのテストカードに相当するものです。実際のプロバイダーを呼び出したり、実際の個人データを扱ったり、残高に触れたりすることなく、任意の検証結果をオンデマンドで再現できます。
#sandboxはアプリケーションのモード
ここが、ほとんどの人がつまずくポイントです。ライブとsandboxは、同じ組織内の別々のアプリケーションであり、テストトラフィックと本番データが混ざることはありません。各アプリケーションには、liveまたはsandboxのいずれかのモードがあります。
- キーは1つのアプリケーションに属します。sandboxアプリのキーは本番セッションに触れられません。
- 本番用のキーを再利用するのではなく、テスト用に別のキーを作成してください。
- 2つ目のアプリケーションを作成する
コンソールの上部にあるアプリケーション切り替えを開き、新しいアプリケーションを作成します。モードとしてsandboxを選択してください。
- そのアプリケーションのAPIキーを使う
sandboxアプリケーションを選択した状態で、API & WebhooksからAPIキーを取得します。本番アプリケーションに独立した「テスト用キー」があるわけではありません。キー自体が環境そのものです。
- その中でワークフローを構築する
sandboxアプリケーションは独自のワークフローを持ちます。テストしたいフローを再構築（またはコピー）してください。
- 通常どおりセッションを作成する
エンドポイントもコードパスも同じです。唯一の違いは、どのキーを送るかだけです。
コンソールに本番用のアプリケーションしか表示されず、sandboxを追加する方法がない場合は、組織向けにsandboxアプリケーション作成を有効化するようサポートに依頼してください。これはアカウントレベルの設定であり、あなたの設定が間違っているわけではありません。
#sandboxが変えるもの、変えないもの
| Sandbox | ライブ | |
|---|---|---|
| 外部プロバイダー | すべてモック化 - サードパーティは一切呼び出されません | 実際に呼び出されます |
| 課金 | 一切課金されません。残高チェックもスキップされます | 完了した機能ごとに課金されます |
| セッション作成の上限 | アプリケーションごとに24時間あたり500件 | 残高に応じます |
| webhookのペイロード | "environment": "sandbox" | "environment": "live" |
| 抽出データとステータス | 選択したシナリオによってシミュレートされます | 実際の撮影内容から導出されます |
| 撮影されたメディア | 実際に保存されます。ライブセッションと全く同様です | 保存されます |
sandboxは、書類、セルフィー、ライブネス動画、住所証明ファイルなど、撮影したメディアをライブセッションと全く同じように保存します。結果はシミュレートされますが、アップロード自体は実際に行われるため、実際の本人確認書類や実際の個人情報ではなく、フローが提供するサンプル書類とテストデータを使用してください。
結果がピクセル内容に一切依存しないため、意図的に悪い写真を使っても、sandboxでは拒否になりません。結果を決めるのはシナリオです。
#結果を選ぶ
セッション作成時にsandbox_scenarioとしてシナリオのスラッグを渡すか、テスト担当者に選ばせることもできます。ホスト型フローのsandboxセッションでは、撮影開始前にカード内のシナリオピッカーが表示され、アップロードコンポーネントの下にサンプル書類のストリップと、常時表示される「テストデータのみ」バナーも表示されます。
シナリオは、実際に対応が必要な結果をカバーしています。
| テストしたい内容 | シナリオ |
|---|---|
| すべて承認 | approve |
| 期限切れの書類 | decline_document_expired |
| 読み取り不能な書類 | decline_could_not_recognize_document |
| MRZチェックサムの失敗 | decline_mrz_validation |
| 最低年齢未満 | decline_minimum_age |
| 顔照合スコアが低すぎる | decline_face_match_low_similarity |
| ライブネスへのなりすまし攻撃 | decline_liveness_attack |
| AML制裁／PEPヒット | decline_aml_hit |
| ブロック済みIPアドレス | decline_ip_blocklist |
| 住所証明の住所不一致 | decline_poa_address_mismatch |
| NFCチップの整合性チェック失敗 | decline_nfc_chip_not_verified |
| データベース検証で該当なし | decline_database_no_match |
| 手動レビューが必要（AML） | review_aml_possible_match |
| 手動レビューが必要（顔照合が境界値） | review_face_match_borderline |
| 手動レビューが必要（住所の部分一致） | review_poa_partial_match |
| KYB登記情報の不一致 | decline_kyb_registry_mismatch |
review_*シナリオは、拒否レベルの入力を用意しなくても、コンソールのレビューキュー、In Reviewのwebhook、レビュアーによる承認や再提出依頼といった、手動レビューの流れ全体を確認できるように用意されています。
シナリオとマジックバリューの最新カタログは、API自体のGET /v1/sandbox/scenarios/から取得できます。ここに記載のスラッグが古く見える場合は、エンドポイントの内容を信頼してください。完全なリファレンス: sandboxテスト。
#自分のコード側で両者を見分ける
すべてのwebhookにはenvironmentフィールドがあり、"sandbox"または"live"のいずれかです。キーから環境を推測しようとするのではなく、このフィールドで分岐すれば、テストセッションを実際の顧客のものと取り違えることはありません。
#sandboxでできないこと
- 実在する企業の実際の登記データは返しません。sandboxのKYBはモック化された登記レスポンスを使用します。
- 実際のSMSやメールは送信しません。電話番号確認とメールアドレス確認はモック化されているため、sandboxで実際のメッセージ配信性をプレビューすることはできません。
- 毎月の無料割り当てを消費しません。これは同時に、sandboxの実行が残りの無料チェック数について何も教えてくれないことも意味します。
#実際のテスト検証が必要な場合
特定の国のデータベースサービスが利用可能かの確認や、特定キャリアへのSMS配信の確認など、本来ライブ呼び出しが必要なケースもあります。その場合はsandboxではなく、ライブアプリケーションへの少額のチャージが必要です。まずサポートに連絡し、そのサービスがアカウントで実際に有効になっているかを確認してから支出するようにしてください。