# 크레딧 없이 sandbox에서 테스트하기

Source: https://help.didit.me/ko/getting-started/sandbox-and-testing
Updated: 2026-10-12

스위치에서 Sandbox를 선택하고 테스트 API 키를 만드세요. 검사는 모의 처리되고 요금이 없으며 원하는 결과를 지정할 수 있습니다.

애플리케이션 이름 아래 스위치에서 **Sandbox**를 선택하고 테스트 API 키를 만들어 사용하세요. 검사는 모의 처리되고 요금이 없으며 원하는 결과를 지정할 수 있습니다.

Didit의 sandbox는 결제 서비스의 테스트 카드와 같은 역할을 합니다.
실제 제공업체를 호출하거나 실제 개인정보를 다루거나 잔액에 손대지 않고도 원하는 검증 결과를 언제든 재현할 수 있습니다.

## 분리된 테스트 환경

Sandbox는 조직이 공유하는 테스트 애플리케이션입니다. 데이터, 키, 웹훅과 목록은 Live와 분리되며 각 페이지 위쪽 띠에서 환경을 확인합니다.

![각 키가 하나의 애플리케이션에 속하는 Didit 콘솔의 API 키 페이지](https://help.didit.me/screenshots/api-keys-light.webp)

*키는 애플리케이션별로 존재하므로, sandbox 키는 절대 라이브 데이터에 닿을 수 없습니다.*

1. **Sandbox로 전환**

   이름 아래 **Sandbox**를 누르세요. **Live**로 돌아가기 전에 워크플로 게시, 라이브 키 또는 링크, 웹훅, 결제와 보관 기간 체크리스트를 확인하고 전환하거나 Sandbox에 남으세요.

2. **테스트 키 만들기**

   **개발자 → API 키**에서 키를 만들 때 Sandbox를 선택하세요. 키가 환경을 결정하므로 라이브 키는 Sandbox 세션을 만들지 않습니다.

3. **워크플로 만들기 또는 복사**

   Sandbox에는 별도의 워크플로가 있습니다. 테스트할 흐름을 만들거나 Live에서 복사하세요.

4. **평소처럼 세션 만들기**

   동일한 엔드포인트, 동일한 코드 경로입니다. 유일한 차이는 어떤 키를 보내느냐입니다.

> **Note:** **Sandbox**가 비활성화되어 있으면 조직에 테스트 애플리케이션이 아직 없습니다. 지원팀에 활성화를 요청하세요. 계정 수준 설정입니다.

## Sandbox가 바꾸는 것, 바꾸지 않는 것

| | Sandbox | Live |
|---|---|---|
| 외부 제공업체 | 전부 모의 처리 - 실제 제3자는 절대 호출되지 않음 | 실제 |
| 과금 | 절대 청구되지 않음, 잔액 확인도 건너뜀 | 완료된 feature마다 청구 |
| 세션 생성 한도 | 애플리케이션당 24시간에 500회 | 보유 잔액만큼 |
| Webhook 페이로드 | `"environment": "sandbox"` | `"environment": "live"` |
| 추출된 데이터와 상태 | 선택한 시나리오로 시뮬레이션됨 | 실제 캡처에서 도출됨 |
| 캡처된 미디어 | 라이브 세션과 똑같이 **실제로 저장됨** | 저장됨 |

> **Warning:** Sandbox는 라이브 세션과 마찬가지로 캡처한 미디어(문서, 셀피, 라이브니스 영상, 주소 증명 파일)를 실제로 저장합니다.
> *결과*는 시뮬레이션되지만 업로드는 실제이므로, 실제 신분증이나 실제 개인정보가 아니라 흐름이 제공하는 샘플 문서와 테스트 데이터를 사용하세요.

결과가 픽셀에 좌우되지 않으므로, 일부러 나쁜 사진을 올려도 sandbox에서는 거절로 이어지지 않습니다.
결과를 결정하는 것은 시나리오입니다.

## 결과 선택하기

세션을 만들 때 `sandbox_scenario`로 시나리오 슬러그를 전달하거나, 테스터가 직접 고르게 할 수도 있습니다.
호스팅된 흐름의 sandbox 세션에서는 캡처가 시작되기 전에 카드 안에 **시나리오 선택기**가 표시되고, 업로드 컴포넌트 아래에 샘플 문서 목록이, 그리고 항상 "test data only" 배너가 함께 표시됩니다.

시나리오는 실제로 구현 과정에서 필요한 결과들을 다룹니다.

| 테스트하려는 것 | 시나리오 |
|---|---|
| 모두 승인 | `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, 재제출을 요청하거나 승인하는 리뷰어 - 를 그대로 연습해 볼 수 있도록 존재합니다.

> **Tip:** 시나리오와 매직 값의 최신 카탈로그는 API 자체에서 `GET /v1/sandbox/scenarios/`로 제공됩니다.
> 여기 있는 슬러그가 오래되어 보인다면 이 엔드포인트를 신뢰하세요.
> 전체 레퍼런스: [sandbox testing](https://docs.didit.me/integration/sandbox-testing).

## 자신의 코드에서 둘을 구분하기

모든 webhook에는 `"sandbox"` 또는 `"live"`값을 가진 `environment` 필드가 포함됩니다.
키로 환경을 추측하려 하지 말고 이 필드로 분기하면, 테스트 세션을 실제 고객으로 착각하는 일이 없습니다.

## Sandbox가 하지 않는 것

- 실제 기업에 대한 실제 등기 데이터를 반환하지 않습니다. Sandbox의 KYB는 모의 등기 응답을 사용합니다.
- 실제 SMS나 이메일을 보내지 않습니다. 전화번호와 이메일 인증은 모의 처리되므로, sandbox로는 실제 메시지 전달 여부를 미리 볼 수 없습니다.
- 월 요금제 크레딧을 소모하지 않습니다. 즉 sandbox 실행 결과로는 남은 크레딧을 알 수 없습니다.

## 실제 테스트 검증이 필요하다면

특정 국가의 데이터베이스 서비스가 계정에 프로비저닝되어 있는지 확인하거나 특정 통신사로 SMS가 실제로 전달되는지 확인하는 등, 실제로 라이브 호출이 필요한 경우도 있습니다.
이런 경우에는 sandbox가 아니라 라이브 애플리케이션에 소액을 충전해야 합니다.
지출하기 전에 지원팀에 문의해, 해당 서비스가 실제로 계정에서 활성화되어 있는지 먼저 확인받으세요.