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

# 리턴 URL 가이드

> KYC 완료 시 또는 오류 페이지 진입 시, 설정된 Return URL과 동적 필드 파라미터로 고객사 서비스에 복귀하는 방법을 안내합니다.

## 1. Dashboard 에서 리턴 URL 옵션 설정하기

Dashboard 에선 리턴 URL 옵션을 설정하실 수 있습니다. KYC 프로세스가 완료되고, 제출자가 "Ok" 버튼을 선택하거나 5초간 대기하면, 동적 필드의 파라미터와 함께 리턴 URL의 주소로 이동됩니다. 2026-04 업데이트부터는 **사용자가 오류 페이지로 이동한 경우에도** 설정된 리턴 URL로 복귀할 수 있으며, 이때는 `errorCode` 파라미터가 함께 전달되어 고객사가 차단 사유를 식별할 수 있습니다.

<img src="https://mintcdn.com/argosidentity/XDoaaMLWTIfazlLD/images/return_url_kr.png?fit=max&auto=format&n=XDoaaMLWTIfazlLD&q=85&s=6cdf7118ba31a1588cec0d298dd7074e" alt="Return Url Kr Pn" width="710" height="390" data-path="images/return_url_kr.png" />

## 2. 동적 필드 내 지원 파라미터

### 2-1. 각 키별 파라미터의 정의

<ResponseField name="userid" type="string">
  제출된 Submission 에 설정된 사용자 ID
</ResponseField>

<ResponseField name="cf1" type="string">
  사용자 정의 필드 #1
</ResponseField>

<ResponseField name="cf2" type="string">
  사용자 정의 필드 #2
</ResponseField>

<ResponseField name="cf3" type="string">
  사용자 정의 필드 #3
</ResponseField>

<ResponseField name="email" type="string">
  제출된 Submission 의 이메일 주소
</ResponseField>

<ResponseField name="submissionId" type="string">
  제출건의 Submission ID
</ResponseField>

<ResponseField name="kycStatus" type="string">
  KYC 결과. `kycStatus`는 camelCase 를 따르므로 대소문자에 주의하세요. 결과에 따라 `approved`, `pending`, `rejected` 중 하나의 값이 리턴됩니다.
</ResponseField>

<ResponseField name="errorCode" type="string">
  **(2026-04 신규)** 사용자가 오류 페이지로 이동한 경우 전달되는 에러 코드입니다. 예: `DE-20000`(Device Verification 실패), `DE-30000`(Fingerprint 탐지), `DE-40000`(Device 중복 초과), `TK-10001`(토큰 만료). 정상 완료 시에는 전달되지 않습니다. 전체 코드 목록은 [에러 코드와 에러 페이지](/ko/idcheck/reference_tables/Error-codes-and-pages)를 참고하세요.
</ResponseField>

### 2-2. 오류 페이지에서 리턴 URL로 복귀

사용자가 사전 검증(Device Info, VPN/Proxy 등) 또는 토큰 검증에서 차단되어 오류 페이지로 이동한 경우, Dashboard 에서 동적 필드의 \*\*에러 코드(`errorCode`)\*\*를 체크해두면 리턴 URL 버튼으로 고객사 서비스에 복귀할 수 있습니다. 이때 전달되는 URL 예시는 다음과 같습니다.

```
https://yourapp.com/verification-complete?kycStatus=rejected&errorCode=DE-20000
```

<Info>
  **errorCode 기반 분기 처리**

  고객사 시스템에서 `errorCode` 값을 기반으로 사용자에게 적절한 후속 안내(예: 모바일 기기 사용 권장, 토큰 재발급 안내 등)를 제공할 수 있습니다.
</Info>

### 2-3. 암호화 적용

암호화 옵션 적용 시, 최종 리턴 URL 에 “encrypted” 파라미터로 응답이 옵니다. 복호화 시 AES-256-ECB 를 통하여 진행하여야 하며, 암복호화 관련 가이드는 [여기](https://developers.argosidentity.com/getting-started/ko/encrypt-and-decrypt-data/overview#3-3-api-%EB%8D%B0%EC%9D%B4%ED%84%B0-%EB%B3%B5%ED%98%B8%ED%99%94-aes-256-ecb)를 참조 바랍니다.

이 가이드를 통해 ID check의 Return URL 옵션을 효과적으로 활용하여 KYC 프로세스를 최적화하고 사용자 경험을 개선할 수 있습니다.