--- title: "CLOVA eKYC 개요" slug: "ai-application-service-ekyc" tags: ["CLOVA eKYC"] updated: 2026-09-17T09:10:00Z published: 2026-09-17T09:10:00Z canonical: "api-fin.ncloud-docs.com/ai-application-service-ekyc" --- > ## Documentation Index > Fetch the complete documentation index at: https://api-fin.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # CLOVA eKYC 개요 CLOVA eKYC는 금융 기관에서 고객의 신원을 식별하고 확인하는 행위인 고객 확인 절차(KYC: Know Your Customer)를 전자적으로 처리할 수 있는 네이버 클라우드 플랫폼의 서비스입니다. CLOVA eKYC에서는 웹이나 모바일로 제출된 신분증의 진위 여부를 검증하는 기능에 대한 API를 RESTful 형태로 제공하며, 사용자 확인이 필요한 민감한 서비스에 적용하여 효율적인 서비스 플로우 설계를 지원합니다. ## CLOVA eKYC 공통 설정 CLOVA eKYC API에서 공통으로 사용하는 요청 형식과 응답 형식을 설명합니다. ### 요청 공통 요청 형식을 설명합니다. #### API URL 도메인 유형별 요청 API URL은 다음과 같습니다. ``` 신분증, 사업자등록증: https://{apigwId}.apigw-pub.fin-ntruss.com/ekyc/v1/{domainId}/{signature}/{inferType} 1원 인증: https://{apigwId}.apigw-pub.fin-ntruss.com/ekyc/v1/{domainId}/{signature}/account ARS 인증: https://{apigwId}.apigw-pub.fin-ntruss.com/ekyc/v1/{domainId}/{signature}/ars 얼굴 인증: https://{apigwId}.apigw-pub.fin-ntruss.com/ekyc/v1/{domainId}/{signature}/face ``` 참고 - API URL(Invoke URL)은 네이버 클라우드 플랫폼 콘솔의 **API 연동** 설정에서 확인할 수 있습니다. - 신분증, 사업자등록증, 1원 인증, ARS 인증, 얼굴 인증 도메인마다 고유의 호출 URL이 생성됩니다. #### 요청 헤더 요청 헤더에 대한 설명은 다음과 같습니다. | 필드 | 필수 여부 | 설명 | | --- | --- | --- | | `X-EKYC-SECRET` | Required | 도메인 연동 시 발급된 Secret Key 값 | | `Content-Type` | Required | 요청 데이터의 형식 - `application/json` \| `multipart/form-data` - `application/json`: Base64로 인코딩된 이미지 전송 - `multipart/form-data`: 이미지 파일 직접 업로드 | #### 요청 경로 파라미터 파라미터에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `apigwId` | String | Required | 도메인 연동 시 생성된 Invoke URL의 API Gateway 식별자 | | `domainId` | String | Required | CLOVA eKYC 콘솔에서 생성한 도메인의 고유 식별자 | | `signature` | String | Required | 요청 인증을 위한 서명 값 | | `inferType` | String | Required | 검증 유형 - `id-card` \| `biz-license` - `id-card`: 신분증 (주민등록증, 운전면허증, 여권, 외국인등록증) - `biz-license`: 사업자등록증 (사업자등록증, 사업자등록증명) | ### 응답 공통 응답 형식을 설명합니다. #### 응답 바디 응답 바디에 대한 설명은 다음과 같습니다. **error** error는 API 호출 실패 정보를 정의합니다. error에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `code` | String | - | 오류 코드 | | `message` | String | - | 오류 메시지 | | `path` | String | - | 오류가 발생한 API 경로 | | `timestamp` | Integer | - | 응답 시간 (Unix Timestamp, 밀리초) | | `uid` | String | - | 시스템에서 생성한 고유 ID | #### 응답 상태 코드 응답 상태 코드에 대한 설명은 다음과 같습니다. | 에러 코드 | HTTP 상태 코드 | 메시지 | 설명 | | --- | --- | --- | --- | | 0001 | 400 | URL is invalid. | URL 오류 | | 0002 | 401 | Secret validate failed. | Secret Key 검증 오류 | | - | 401 | 로그인 해주세요. | 인증 오류 | | 0011 | 400 | Request invalid. | 요청 바디 오류 | | 0012 | 400 | RequestId is duplicated. | 요청 ID 중복 | | 0022 | 400 | Request domain invalid. | 도메인 조회 불가능 | | 0024 | 400 | Data is duplicated. | 요청 데이터 중복 | | 0025 | 400 | Calls to this api have exceeded the rate limit. | 일시적으로 도메인별 API 호출 허용량 초과 | | 0027 | 400 | The system is busy. | 일시적으로 API 호출 허용량 초과 | | - | 404 | 페이지를 찾을 수 없습니다. | - | | 0500 | 500 | Unknown service error. | 알 수 없는 오류 | | 0501 | 500 | OCR service error. | OCR 엔진에서 발생한 오류 | | 0509 | 500 | Verify service error. | 진위 검증 시 오류가 발생하거나 특정할 수 없는 원인으로 실패 | | 0510 | 500 | IDCard verification is locked. | 주민등록증 진위 검증 시 발급 일자 입력 오류가 5회 이상 발생하여 요청이 잠김 - **정부24(gov.kr) > 서비스 > 신청/확인/공유 > 사실/진위확인 > 주민등록증 진위확인/잠김해제**에서 간편인증서 혹은 공동인증서로 인증 후 해제 | | 0511 | 200 | [진위 검증 기관 에러 메시지](/docs/ai-application-service-ekyc#%EC%A7%84%EC%9C%84%EA%B2%80%EC%A6%9D%EA%B8%B0%EA%B4%80%EC%97%90%EB%9F%AC%EB%A9%94%EC%8B%9C%EC%A7%80) 참조 | 입력값 오류로 진위 검증에 실패 | | 0512 | 200 | [진위 검증 기관 에러 메시지](/docs/ai-application-service-ekyc#%EC%A7%84%EC%9C%84%EA%B2%80%EC%A6%9D%EA%B8%B0%EA%B4%80%EC%97%90%EB%9F%AC%EB%A9%94%EC%8B%9C%EC%A7%80) 참조 | 신분증이 만료되거나 분실 신고됨 | | 0590 | 200 | [진위 검증 기관 에러 메시지](/docs/ai-application-service-ekyc#%EC%A7%84%EC%9C%84%EA%B2%80%EC%A6%9D%EA%B8%B0%EA%B4%80%EC%97%90%EB%9F%AC%EB%A9%94%EC%8B%9C%EC%A7%80) 참조 | 등록되지 않은 사업자등록번호 | | 0591 | 200 | [진위 검증 기관 에러 메시지](/docs/ai-application-service-ekyc#%EC%A7%84%EC%9C%84%EA%B2%80%EC%A6%9D%EA%B8%B0%EA%B4%80%EC%97%90%EB%9F%AC%EB%A9%94%EC%8B%9C%EC%A7%80) 참조 | 폐업된 사업자등록번호 | | 0592 | 200 | [진위 검증 기관 에러 메시지](/docs/ai-application-service-ekyc#%EC%A7%84%EC%9C%84%EA%B2%80%EC%A6%9D%EA%B8%B0%EA%B4%80%EC%97%90%EB%9F%AC%EB%A9%94%EC%8B%9C%EC%A7%80) 참조 | 휴업 상태의 사업자등록번호 | | 0600 | 400 | Trial usage error. | Trial 요금제 사용 시 도메인이 만료되거나 사용 횟수 초과 | | 2002 | 200 | 데이터 처리중 오류가 발생하였습니다. | 1원인증 내부 모듈에서 발생하는 메시지 | | 2107 | 200 | 계좌검증 거래정보가 불일치 합니다.(원거래 실패) | 1원인증 내부 모듈에서 발생하는 메시지 | | 2109 | 200 | 예금주명이 불일치 합니다. | 1원인증 내부 모듈에서 발생하는 메시지 | | 2111 | 200 | 계좌검증번호가 일치하지 않습니다. 다시 정확하게 입력하여 주십시오. | 1원인증 내부 모듈에서 발생하는 메시지 | | 2119 | 200 | 계좌검증 거래정보가 없습니다. | 1원인증 내부 모듈에서 발생하는 메시지 | | 2201 | 200 | 거래가 원활하지 않습니다. 잠시 후 다시 시도하여 주십시오. | 1원인증 내부 모듈에서 발생하는 메시지 | | 2202 | 200 | 은행코드를 확인해 주세요. | 1원인증 내부 모듈에서 발생하는 메시지 | | 2203 | 200 | 은행점검시간입니다. 잠시 후 다시 시도하여 주십시오. | 1원인증 내부 모듈에서 발생하는 메시지 | | 2204 | 200 | 계좌번호를 확인해 주세요. | 1원인증 내부 모듈에서 발생하는 메시지 | | 2299 | 200 | 계좌정보를 확인하거나 잠시 후 다시 시도하여 주십시오. | 1원인증 내부 모듈에서 발생하는 메시지 | | 2999 | 200 | Account 서비스 오류 | 1원인증 내부 모듈에서 발생하는 메시지 | | 3001 | 200 | 인증실패 | ARS인증 내부 모듈에서 발생하는 메시지 (FAILURE) | | 3007 | 200 | 전화를 받지 않음 | ARS인증 내부 모듈에서 발생하는 메시지 | | 3008 | 200 | 수신자가 전화를 받은 후 끊음 | ARS인증 내부 모듈에서 발생하는 메시지 (FAILURE) | | 3009 | 200 | 인증번호입력 타임아웃1회 | ARS인증 내부 모듈에서 발생하는 메시지 (FAILURE) | | 3010 | 200 | 인증번호입력 타임아웃2회 | ARS인증 내부 모듈에서 발생하는 메시지 (FAILURE) | | 3012 | 200 | 인증번호불일치 1회 | ARS인증 내부 모듈에서 발생하는 메시지 (FAILURE) | | 3013 | 200 | 인증번호불일치 2회 | ARS인증 내부 모듈에서 발생하는 메시지 (FAILURE) | | 3016 | 200 | 인증거절 | ARS인증 내부 모듈에서 발생하는 메시지 (FAILURE) | | 3021 | 200 | 고객에게 전화콜이 나가기 전에 동일한 수신자번호로 인증요청 | ARS인증 내부 모듈에서 발생하는 메시지 | | 3022 | 200 | 고객에게 벨소리가 울리는 상태일 때 동일한 수신자번호로 인증요청 | ARS인증 내부 모듈에서 발생하는 메시지 | | 3023 | 200 | 고객이 통화중일 때 동일한 수신자번호로 인증요청 | ARS인증 내부 모듈에서 발생하는 메시지 | | 3902 | 200 | ARS 처리중입니다. 잠시후에 다시 조회하여 주십시오. | ARS인증 내부 모듈에서 발생하는 메시지 | | 3999 | 200 | ARS 서비스 오류 | ARS인증 내부 모듈에서 발생하는 메시지 | #### 진위 검증 기관 에러 메시지 진위 검증 기관 에러 메시지에 대한 설명은 다음과 같습니다. 참고 - 제3 인증 기관에서 반환하는 메시지입니다. - 아래 메시지는 향후 숫자 및 코드를 제거하고 최신화할 예정입니다. - <예시> '1012:****:여권정보가 일치하지 않습니다.'는 '여권정보가 일치하지 않습니다.'로 변경 - 메시지 분기 처리가 필요한 경우, 되도록 코드 필드를 활용해 주십시오. 메시지는 인증 기관에 의해 변경될 수 있습니다. | 검증 유형 | 코드 | 메시지 | | --- | --- | --- | | 주민등록증 | 0511 | 335:****:인적자료(성명, 주민번호)를 잘못 입력하였습니다. | | 외국인등록증 | 0511 | 1104:****:민원인의 정보를 확인할 수 없습니다.민원신청을 원할시 관할 출입국.외국인관서로 문의 바랍니다. | | 외국인등록증 | 0512 | 1104::법무부가 보유한 정보와 일치하나 분실 또는 발급 취소한 외국인 등록번호 입니다. | | 운전면허증 | 0511 | 716:****:면허 번호가 일치하지 않음 | | 운전면허증 | 0511 | 217:****: 도로교통공단 전산 자료와 일치하지 않습니다. | | 운전면허증 | 0511 | 217:****:인적 정보를 잘못 입력하였습니다. | | 운전면허증 | 0511 | 217:****:암호일련번호가 일치하지 않습니다. | | 여권 | 0511 | 1012:****:여권정보가 일치하지 않습니다. | | 사업자등록증 | 0590 | 조회하신 사업자등록번호는 현재 등록되어 있지 않습니다. | | 사업자등록증 | 0591 | 폐업 사업자입니다. | | 사업자등록증 | 0592 | 휴업 사업자입니다. | #### 응답 예시 호출이 성공한 경우의 응답 예시는 각 API 명세에서 확인해 주십시오. 호출이 실패한 경우의 응답 예시는 다음과 같습니다. ``` { "code": "0002", "message": "Secret validate failed.", "path": "/external/v1/{domainId}/{signature}/id-card/document", "timestamp": 1700000000000, "uid": "a1b2c3d4e5f6g7h8i9j0k1l2m3" } ``` ## CLOVA eKYC API CLOVA eKYC 서비스에서 제공하는 API에 대한 설명은 다음과 같습니다. | API | 설명 | | --- | --- | | [Document](/docs/ai-application-service-ekyc-document-api) | 신분증 또는 사업자등록증 이미지 인식 | | [Verify](/docs/ai-application-service-ekyc-verify-api) | 신분증 또는 사업자등록증 정보의 진위 검증 | | [eKYC](/docs/ai-application-service-ekyc-api) | 신분증 또는 사업자등록증의 이미지 인식과 인식한 정보의 진위 검증을 한번에 수행 | | [Account](/docs/clova-ekyc-account-api) | 1원 계좌 인증 | | [ARS](/docs/clova-ekyc-ars-api) | ARS 인증 | | [Face Compare](/docs/clova-ekyc-facecompare-api) | 신분증 얼굴과 실제로 촬영한 얼굴 비교 | ## CLOVA eKYC 연관 리소스 CLOVA eKYC API에 대한 사용자의 이해를 돕기 위해 다양한 연관 리소스를 제공하고 있습니다. - CLOVA eKYC 서비스 사용 방법 - [CLOVA eKYC 사용 가이드](https://guide-fin.ncloud-docs.com/docs/clovaekyc-overview): 네이버 클라우드 플랫폼 콘솔에서 CLOVA eKYC 서비스를 사용하는 방법 - [요금 소개, 특징, 상세 기능](https://www.fin-ncloud.com/v2/product/aiService/clovaEkyc): CLOVA eKYC 서비스의 요금 체계, 특징, 상세 기능 요약 - [서비스 최신 소식](https://www.fin-ncloud.com/v2/intro/news?categoryCode=AI): CLOVA eKYC 서비스 관련 최신 소식 - [자주 하는 질문](https://www.fin-ncloud.com/v2/support/faq/prod?categoryCode2=AI&categoryCode3=SV_0196): CLOVA eKYC 서비스 사용자들이 자주 하는 질문 - [문의하기](https://www.fin-ncloud.com/v2/support/question/service): API 가이드를 통해서도 궁금증이 해결되지 않는 경우 직접 문의