Account API

1원 계좌 인증 API 가이드입니다. API는 인증(Verify)과 확인(Confirm) 2단계로 나뉘며, 이용 이력 및 통계는 인증 단계에서 발생합니다.

인증 API

인증 단계에서 요청 및 응답을 설명합니다.

요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

메서드	URI
POST	/verify

요청 헤더

CLOVA eKYC API에서 공통으로 사용하는 헤더에 대한 정보는 CLOVA eKYC 요청 헤더를 참조해 주십시오.

요청 바디

요청 바디에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`requestId`	String	Required	사용자가 지정한 요청 ID (10분간 재사용 불가) 확인 API 호출 시 재사용
`bankCode`	String	Required	1원 계좌 인증에 사용되는 3자리 은행 코드: bankCode 참조
`accountNo`	String	Required	계좌번호 최대 16자
`name`	String	Required	예금주명 최대 20자 부분만 일치해도 요청 가능 이름이 홍길동인 경우, '길'이나 '길동'만 입력해도 요청됨 법인, 외국인 이름 등 특수한 상황에서 오류를 줄이기 위해 부분 비교 정책 제공
`verifyType`	String	Required	인증 유형: verifyType 발송 유형에 따라 인증 번호 또는 문자 결정
`verifyLength`	String	Optional	인증 번호 자릿수 1~4자리 (기본값: 3자리)
`text`	String	Conditional	적요 1~3자리 `verifyType`이 `NORMAL`, `A2`, `A3`, `REVERSE`인 경우, 필수 입력

`bankCode`

BankCode에 대한 설명은 다음과 같습니다.

코드	이름
002	산업은행
003	기업은행
004	국민은행
005	KEB 하나은행 (구 외환은행)
007	수협은행
008	수출입은행
011	농협은행
020	우리은행
023	SC 제일은행
027	씨티은행
031	대구은행
032	부산은행
034	광주은행
035	제주은행
037	전북은행
039	경남은행
045	새마을금고
048	신협
050	상호저축은행
054	HSBC
055	도이치
057	JP 모간
060	BOA
061	비엔피파리바은행
062	중국공상은행
064	산림조합
071	우체국
088	신한은행
089	K 뱅크
090	카카오뱅크
092	토스뱅크
209	유안타증권
218	현대증권
230	미래에셋
238	대우증권
240	삼성증권
243	한국투자
247	NH 투자증권
261	교보증권
262	하이투자
263	HMC 증권
264	키움증권
265	이베스트증권
266	SK 증권
267	대신증권
268	아이엠투자증권
269	한화증권
270	하나대투
278	신한금융투자
279	동부증권
280	유진투자증권
287	메리츠증권
290	부국증권
291	신영증권
292	LIG 투자증권

`verifyType`

적요는 받는 분에게 표시되는 내용으로 인증 요청자 또는 회사명 등을 표기해, 인증 요청을 구분할 수 있습니다. 적요에 포함되는 숫자 또는 텍스트를 인증값으로 발송합니다.
NORMAL 및 REVERSE 유형에서는 verifyLength에 따라 인증번호 자릿수가 달라지며, 값이 없으면 기본값 3이 적용됩니다.

인증 유형	설명
`NORMAL`	적요와 숫자 발송 <예시> 네이버123
`TEXT`	적요로 4자리 문자 발송 <예시> 푸른나무
`A2`	적요와 1자리 영문자, 2자리 숫자 발송 <예시> 네이버A12
`A3`	적요와 1자리 영문자, 3자리 숫자 발송 <예시> 네이버A123
`REVERSE`	숫자와 적요 발송 <예시> 123네이버

요청 예시

요청 예시는 다음과 같습니다.

curl --location --request POST 'https://{apigwId}.apigw-pub.fin-ntruss.com/ekyc/v1/{domainId}/{signature}/account/verify' \
--header 'X-EKYC-SECRET: {secret-key}' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "request-001",
  "bankCode": "020",
  "accountNo": "OOOO-OOO-OOOOOO",
  "name": "홍길동",
  "verifyType": "NORMAL",
  "verifyLength": "3",
  "text": "네이버"
}'

응답

응답 형식을 설명합니다.

응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`requestId`	String	-	사용자가 지정한 요청 ID
`timestamp`	Integer	-	응답 시간 (Unix Timestamp, 밀리초)
`uid`	String	-	시스템에서 생성한 고유 ID
`inferType`	String	-	인증 유형 `ACCOUNT`
`inferDetailType`	String	-	상세 인증 유형 요청 시 전달된 `verifyType`
`result`	String	-	호출 결과 `SUCCESS` \| `ERROR` `SUCCESS`: 호출 성공 `ERROR`: 호출 오류 (과금 미발생)
`code`	String	-	4자리 에러 코드
`message`	String	호출 결과 메시지

응답 상태 코드

CLOVA eKYC API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 CLOVA eKYC 응답 상태 코드를 참조해 주십시오.

응답 예시

응답 예시는 다음과 같습니다.

성공

{
  "requestId": "request-001",
  "uid": "a1b2c3d4e5f6g7h8i9j0k1l2m3",
  "timestamp": 1700000000000,
  "inferType": "ACCOUNT",
  "inferDetailType": "NORMAL",
  "result": "SUCCESS",
  "message": "Success"
}

오류

{
    "requestId": "request-002",
    "uid": "a1b2c3d4e5f6g7h8i9j0k1l2m3",
    "timestamp": 1700000000000,
    "inferType": "ACCOUNT",
    "inferDetailType": "A2",
    "result": "ERROR",
    "code": "2204",
    "message": "계좌번호를 확인해주세요."
}

확인 API

확인 단계에서 요청 및 응답을 설명합니다.

요청