CLOVA eKYC Account API
- 인쇄
- PDF
CLOVA eKYC Account API
- 인쇄
- PDF
기사 요약
이 요약이 도움이 되었나요?
의견을 보내 주셔서 감사합니다.
버전
| 날짜 | 변경사항 |
|---|---|
| 2023-05-25 | 최초 작성 |
개요
1원 계좌 인증 API 가이드입니다. API는 인증(Verify)과 확인(Confirm) 2단계로 나뉘며, 이용 이력 및 통계는 인증 단계에서 발생합니다.
인증
인증요청
| 메서드 | 요청 URI |
|---|---|
| POST | - API 연동설정의 InvokeURL 과 API 경로의 조합으로 호출 - 각 도메인마다 고유의 호출 URL이 생성됨 |
API 요청 예시
curl -X POST "{invokeUrl}/verify" \
-H "X-EKYC-SECRET: {secretKey}" \
-H "Content-Type: application/json" \
-d "{ \"accountNo\": \"{accountNo}\", \"bankCode\": \"{backCode}\", \"name\": \"{name}\", \"requestId\": \"{requestId}\", \"text\": \"{text}\", \"verifyType\": \"{verifyType}\", \"verifyLength\": \"{verifyLength}\"}"
요청헤더
| 이름 | 설명 |
|---|---|
| X-EKYC-SECRET | API 연동설정에서 생성한 X-EKYC-SECRET:{Client Secret} |
| Content-Type | application/json |
요청바디
| 필드이름 | 필수여부 | 데이터유형 | 설명 | 제약사항 |
|---|---|---|---|---|
| requestId | Yes | string | API 요청ID | 임의값으로 호출합니다. Confirm API 호출 시에 재사용합니다. 동일한 requestId는 10분간 재사용 불가능합니다. |
| bankCode | Yes | string | 은행코드 | 3자리 은행코드 참조 |
| accountNo | Yes | string | 계좌번호 | 최대 16자까지 가능합니다 |
| name | Yes | string | 예금주 | 최대 20자까지 가능하며, 예금주명은 부분 일치만 해도 요청 가능합니다. - 예) 홍길동인 경우 길이나 길동만 입력해도 요청됨. 법인, 외국인 이름 등 특수한 상황에서 오류를 줄이기 위해 부분 비교 정책이 제공되고 있습니다. |
| verifyType | Yes | string | 인증유형 | 발송유형에 따라 인증 번호 또는 문자가 결정됩니다. 5가지 유형을 제공합니다. 아래 VerifyType 정의 를 참고해 주십시오. |
| verifyLength | No | string | 인증번호 자릿수 | 1~4 |
| text | No | string | 적요 | 1~3자리 |
VerifyType 정의
적요는 받는 분에게 표시되는 내용으로 인증 요청자 또는 회사명 등을 표기해, 인증 요청을 구분할 수 있습니다. 적요에 포함되는 숫자 또는 텍스트를 인증값으로 발송합니다.
Normal 및 Reverse 유형에서는 verifyLength에 따라 인증번호 자릿수가 달라지며, 값이 없으면 기본값 3이 적용됩니다.
| 이름 | 발송유형 (예시) | 인증값(예시) | 설명 | 인증값 |
|---|---|---|---|---|
| NORMAL | 적요+숫자 (네이버123) | 123 | 적요와 숫자를 발송합니다. | 적요 뒤 숫자 |
| TEXT | 적요4 (푸른나무) | 푸른나무 | 적요로 4자리 문자를 발송합니다. | 모든 텍스트 |
| A2 | 적요+영문자1+숫자2 **(네이버A12) | A12 | 적요와 하나의 영문자와 2자리 숫자를 발송합니다. | 적요 뒤 문자 및 숫자 |
| A3 | 적요+영문자1+숫자3 (네이버A123) | A123 | 적요와 하나의 영문자와 3자리 숫자를 발송합니다. | 적요 뒤 문자 및 숫자 |
| REVERSE | 숫자+적요 (123네이버) | 123 | 숫자와 적요를 발송합니다. | 적요 앞 숫자 |
응답
응답바디
| 필드명 | 데이터유형 | 설명 |
|---|---|---|
| requestId | string | API 요청ID |
| timestamp | integer | API 응답 Timestamp 값 |
| uid | string | API 응답 UUID |
| inferType | string | 1원 계좌인증 유형 "ACCOUNT" 로 응답 |
| inferDetailType | string | 상세유형 : 요청시 전달된 verifyType |
| result | string | "SUCCESS" : 호출 성공 "ERROR" : 호출 오류(과금 미발생) |
| code | string | 4자리 에러코드 |
| message | string | 호출 결과 메시지 |
예시
{
"requestId": "abb3fcb0-2566-44f4-badd-202be9621c15",
"uid": "5dc74e2d398543e0a36fea0294b1c010",
"timestamp": 1684916415923,
"inferType": "ACCOUNT",
"inferDetailType": "A2",
"result": "SUCCESS",
"message": "Success"
}
{
"requestId": "abb3fcb0-2566-44f4-badd-202be9621c15",
"uid": "3cdr660o38c9n36dr5cormcc1i",
"timestamp": 1684917556241,
"inferType": "ACCOUNT",
"inferDetailType": "A2",
"result": "ERROR",
"code": "2204",
"message": "계좌번호를 확인해주세요."
}
확인
확인 요청
| 메서드 | 요청 URI |
|---|---|
| POST | - API 연동설정의 InvokeURL 과 API 경로의 조합으로 호출 - 각 도메인마다 고유의 호출 URL이 생성됨 |
API 요청 예시
curl -X POST "{invokeUrl}/confirm" \
-H "X-EKYC-SECRET: {secret}" \
-H "Content-Type: application/json" \
-d "{\"requestId\": \"{requestId}\", \"verifyValue\": \"{verifyValue}\"}"
요청헤더
| 이름 | 설명 |
|---|---|
| X-EKYC-SECRET | API 연동설정에서 생성한 X-EKYC-SECRET:{Client Secret} |
| Content-Type | application/json |
요청바디
| 필드이름 | 필수여부 | 데이터유형 | 설명 | 제약사항 |
|---|---|---|---|---|
| requestId | Yes | string | API 요청ID | 인증 요청에서 호출했던 requestId 를 사용 |
| verifyValue | Yes | string | 인증값 | VerifyType 정의참조 |
확인응답
응답바디
| 필드명 | 데이터유형 | 설명 |
|---|---|---|
| requestId | string | API 요청ID |
| timestamp | integer | API 응답 Timestamp 값 |
| uid | string | API 응답 UUID 입니다 |
| inferType | string | 1원 계좌인증 유형 "ACCOUNT" 로 응답 |
| inferDetailType | string | 상세유형 : 인증요청시 전달된 verifyType |
| result | string | "SUCCESS" : 호출 성공 "ERROR" : 호출 오류(과금 미발생) |
| code | string | 4자리 에러코드 |
| message | string | 호출 결과 메시지 |
예시
{
"requestId": "abb3fcb0-2566-44f4-badd-202be9621c15",
"uid": "3gopl70s6ac1o3ed9l68pj0d1g",
"timestamp": 1684917397193,
"inferType": "ACCOUNT",
"inferDetailType": "A2",
"result": "SUCCESS",
"message": "Success"
}
{
"requestId": "abb3fcb0-2566-44f4-badd-202be9621c15",
"uid": "36d3374q6ceb534cr160sjge34",
"timestamp": 1684917401450,
"inferType": "ACCOUNT",
"inferDetailType": "A2",
"result": "ERROR",
"code": "2111",
"message": "계좌검증번호가 일치하지 않습니다. 다시 정확하게 입력하여 주십시오."
}
에러코드
| HTTP 상태 | 설명 |
|---|---|
| 200 | 요청에 성공했으나, 내부적으로 오류가 있는 경우 |
| 400 | 요청 에러 |
| 401 | 권한 에러 |
| 500 | 내부 서버 에러 |
에러응답:
{
"code": "0011",
"message": "Request body invalid.",
"path": "{request API path}",
"timestamp": 1570776853475
}
| 에러코드 | HTTP 상태 | 메시지 | 설명 |
|---|---|---|---|
| 0001 | 400 | URL is invalid. | URL 오류 |
| 0002 | 401 | Secret key validate failed. | Secret 인증 오류 |
| 0011 | 400 | Request body 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 호출 허용량을 초과한 경우 |
| 0500 | 500 | Unknown service error. | 알 수 없는 오류 |
| 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원인증 내부 모듈에서 발생하는 메시지 |
이 문서가 도움이 되었습니까?