샌드박스 테스트 데이터: 시나리오, 매직 값, 문서

​

환경 모델

• 모든 외부 제공업체(OCR, AML, 얼굴 대조, 라이브니스, NFC, 전화, 이메일, IP, 주소 증명, 데이터베이스 검증, 문서 AI)가 모의(mock) 처리됩니다. 어떤 제3자도 호출되지 않습니다.
• 라이브니스는 실제 환경과 똑같이 동작합니다. 능동형 라이브니스 워크플로는 호스팅 흐름과 네이티브 SDK의 웹 핸드오프 모두에서 샌드박스에서도 실제 능동형 캡처를 실행하므로, 사용자가 실제로 겪게 될 경험을 테스트할 수 있습니다. 라이브니스 결과만 시나리오 또는 매직 값으로 시뮬레이션되며, 보고서에는 워크플로에 설정된 방식이 기록됩니다.
• 커스텀 도메인은 라이브 환경에서만 사용할 수 있습니다. 샌드박스 애플리케이션에는 커스텀 도메인을 추가할 수 없으며, 샌드박스 세션은 항상 기본 호스팅 인증 도메인에서 실행됩니다.
• 세션은 청구되지 않으며, 잔액 확인도 건너뜁니다.
• 애플리케이션별로 24시간 동안 세션 생성 500회 할당량이 적용됩니다.
• webhook에는 "environment": "sandbox"가 포함됩니다(라이브 세션의 webhook에는 "environment": "live"가 포함됩니다).
• 호스팅 흐름은 세션 환경 정보를 노출하므로, UI에서 사용자에게 실제 개인정보를 업로드하지 말라고 경고할 수 있습니다.
• 결과는 픽셀에 의존하지 않습니다. 추출된 데이터와 상태는 시나리오 또는 매직 값에서 가져옵니다. 캡처된 미디어 자체(문서, 셀피, 영상, 주소 증명 파일)는 라이브 세션과 똑같이 실제로 저장됩니다.

​

샌드박스의 거래 모니터링

• 규칙 평가 없음. 규칙 모드와 관계없이 rule_runs는 비어 있습니다. 샌드박스 애플리케이션에서는 ACTIVE 규칙이 절대 발동하지 않으므로, 거래는 점수 0과 함께 APPROVED 상태를 유지하며 알림이나 케이스가 생성되지 않습니다.
• AML / 지갑 스크리닝 없음. 모니터링이 활성화된 애플리케이션이라도 암호화폐 거래의 경우 provider_results는 비어 있습니다.
• webhook 없음. 샌드박스 거래에 대해서는 transaction.created와 transaction.status.updated가 모두 전송되지 않습니다.
• 청구 없음. 사용량 이벤트는 가격 0.0000으로 기록되며 잔액은 변하지 않습니다.

​

Travel Rule 테스트 VASP 시나리오

​

라이브와 샌드박스 전환 방법

• 샌드박스 모드 애플리케이션의 API 키를 사용하면 모의 세션을 얻을 수 있습니다. 이 세션은 과금되지 않으며 시뮬레이션할 수 있습니다.
• 라이브 모드 애플리케이션의 API 키는 실제 인증에 사용합니다.

​

호스팅 인증 흐름의 샌드박스

• 카드 내 샌드박스 배너. 모든 화면의 카드 안에 “테스트 데이터만 사용 - 실제 호출 없음” 배너가 표시됩니다. 따라서 이 세션이 실제 제공업체를 호출하지 않고 잔액에도 영향을 주지 않는다는 점이 항상 분명합니다. 캡처된 미디어는 일반 세션과 같은 방식으로 저장되므로, 실제 신분증이나 개인정보 대신 샘플 문서와 테스트 데이터를 사용하십시오.
• 흐름 시작 전 시나리오 선택기. 캡처를 시작하기 전에 카드 내 선택기가 사용자가 테스트 결과를 고르도록 안내합니다. 먼저 결과를 선택하고, 그 결과에 대한 트리거를 고릅니다. 확인하면 POST /v3/session/{session_id}/sandbox/arm/이 호출되고(흐름 시작 전 세션 설정(또는 재설정) 참조), 해당 시나리오의 모의 값이 이미 적용된 상태로 흐름이 이어집니다.
• 샘플 문서 스트립. 문서 업로드/캡처 컴포넌트 바로 아래에 샌드박스 샘플 문서가 한 줄로 최대 3개까지 표시됩니다. 하나를 탭하면 실제 업로드 대신 그 문서를 사용합니다.

​

시나리오

​

매직 값

​

비문서 조회 및 신원 지갑

​

은행 인증 계좌 확인

​

샘플 문서

​

샘플 신원: 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을 반환합니다.

​

샌드박스 결과 제어: 시나리오, 매직 값, 사전 설정, 시뮬레이션 endpoint

​

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으로 인증합니다. 이 endpoint는 클라이언트용 endpoint입니다.
• 알 수 없는 시나리오 슬러그이면 400을 반환하고, 세션이 Not Started 상태를 지난 후에는 400을 반환합니다("Scenario can only be armed before the verification starts.").
• Session-Token이 라이브(샌드박스가 아닌) 애플리케이션에 속하거나 경로의 session_id와 일치하지 않으면 404를 반환합니다.
• 시나리오를 다시 설정하면 이전 시나리오가 대체됩니다. 이전 시나리오가 기록한 매직 값만 지워지고, 사용자가 직접 입력한 값(이메일, 이름 등)은 그대로 유지됩니다. 예를 들어 decline_phone_high_risk를 설정한 뒤 approve를 설정하면 전화번호는 미설정 상태로 돌아가지만, 고객이 입력한 이메일은 두 호출 모두에서 유지됩니다.

​

4. 시뮬레이션 endpoint

• 콘솔 / 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는 요청한 슬러그를 그대로 반환하고, risk는 적용된 위험 사례입니다. 해당하는 값이 없으면 각각 null입니다.
• send_webhooks는 적용된 값을 반환합니다.
• 알 수 없는 시나리오나 위험 사례이거나, new_status를 도출할 수 없거나, 지원하지 않는 new_status이거나, 세션이 이미 요청된 상태를 가지고 있으면 400을 반환합니다(["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은 실제 운영 환경과 같은 형식의 일치 결과를 하나 반환하고 스크리닝을 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/에서 조회할 수 있습니다.
• 알 수 없는 시나리오 슬러그이면 400을 반환하고, API 키가 라이브 애플리케이션에 속하면 400을 반환합니다.

​

sandbox_scenario가 표시되는 위치

​

사용량 및 결제

• 모의 호출마다 사용량 이벤트가 기록됩니다(is_sandbox: true, 가격 0.0000). 디버깅을 위해 샌드박스 사용량을 확인할 수 있도록 하기 위함이며, 사용량 합계에 더해지지 않고, 잔액에서 차감되지 않으며, 청구서에도 나타나지 않습니다.
• Business Console의 잔액, 충전, 실시간 사용량 화면은 기본적으로 샌드박스 사용량을 제외합니다. 충전 사용량 endpoint는 environment 파라미터(live가 기본값이고 sandbox 선택 가능)를 받으므로, 샌드박스 사용량을 따로 조회할 수 있습니다. 이때 비용은 항상 0이며 무료 요금제 사용량도 차감되지 않습니다.
• 이메일 및 전화번호 인증은 세션 결과 단위가 아니라 요청 단위로 결제됩니다. 샌드박스는 웹훅 계층에서 이를 완전히 반영할 수 없습니다. 샌드박스의 이메일/전화번호 인증도 다른 모의 기능과 마찬가지로 요청마다 가격 0.0000의 사용량 이벤트를 기록합니다. 이는 실제 결제 동작과의 알려진 차이로, 의도된 설계이며 버그가 아닙니다.
• 데이터베이스 검증의 샌드박스 응답 형식은 실제 제공자가 없으므로 프로덕션 환경의 제공자별 형식과 의도적으로 다릅니다. 샌드박스의 데이터베이스 검증 payload는 결과(상태 및 경고 코드)를 대신하는 값으로 취급하고, 실제 제공자 응답을 바이트 단위로 미리 보여주는 것으로 간주하지 마십시오.