POST/Submission/Step 1
STEP 1
ID check 제출 단계는 Step1 -> Step2로 나뉩니다.
Step1은 신분증의 정보를 추출하고 확인하는 단계입니다.
Step1은 form-data 형식으로 제출해야 합니다.
Step1에서 submission_id(제출 ID)가 생성되지 않았다면 Step2를 진행할 수 없습니다.
Step1 에서는 발급 국가, 신분증 타입, 이메일, 신분증 이미지 데이터를 필수로 요구합니다.
idImage와 idBackImage 표준 권장 사양은 640 x 480 픽셀 입니다.
userid, cf1, cf2, cf3 값은 필수로 요구하지 않습니다. 상세 내용은 하단의 Input Data 표를 참조하세요.
Retry code와 error code는 Retry/Error/Reject Codes 페이지에서 확인해 주세요.
Input Data
*이 붙은 것은 필수 파라미터 입니다.
*issuingCountry
ISO alpha 3 형식의 신분증이 발행된 국가
string
KYC 제출자의 이메일 주소
*idType
string
government_id, passport, drivers_license, residence_permit, vehicle_registration_certificate, visa, aadhaar, pancard, universal
*idImage
file
jpg, jpeg, png 파일 형식의 신분증 앞면 이미지
(권장 용량: 1mb, 최대: 2mb)
idBackImage
file
jpg, jpeg, png 파일 형식의 신분증 뒷면 이미지 (권장 용량: 1mb, 최대: 2mb)
submissionId
string
각각의 submission을 구분하는 고유의 구분자로 이후 프로세스 진행에 필요하며, createTime으로부터 4시간 동안 유효
userid
string
사용자의 사용자 지정 고유 식별자
cf1
string
사용자 정의 옵션 필드
cf2
string
사용자 정의 옵션 필드
cf3
string
사용자 정의 옵션 필드
customOptions
serialized JSON object in string
프로젝트옵션과 무관하게, 각각의 submission 별로 옵션을 적용하기 위한 객체(object). String 으로 변환하여 전송.
customOptions. blacklistCountries
boolean
블랙리스트 국가에 대한 옵션을 해당 submission 에 대하여 OFF 함 (’false’ 만 가능)
customOptions. approvePeriod
boolean
Approved 중복 제출 방지 기간에 대한 옵션을 해당 submission 에 대하여 OFF 함 (’false’ 만 가능)
customOptions. rejectPeriod
boolean
Rejected 중복 제출 방지 기간에 대한 옵션을 해당 submission 에 대하여 OFF 함 (’false’ 만 가능)
customOptions. ageLimit
boolean
연령 제한에 대한 옵션을 해당 submission 에 대하여 OFF 함 (’false’ 만 가능)
customOptions. rejectDuplicateUser
boolean
중복 제출 방지에 대한 옵션을 해당 submission 에 대하여 ON / OFF 함 (’true’ 및 ‘false’ 모두 가능)
‘customOptions’ 상세 설명
customOptions 자체는 내부에 옵션 사용 여부(boolean) 프로퍼티를 담은 객체(Object)임.
단, 객체 전체를 String 으로 변환하여 전송해야 함.
오직 Step1 에서만 제출 가능하며, Step2 에서도 이를 참조함.
rejectDuplicateUser 의 경우에만 ON/OFF 가능함.
Example
*'issuingCountry'와 'idType', 뒷면 수집 여부는 '신분증별 뒷면 수집 여부' 페이지를 참고해 주세요.
Sample Request 1
Sample Request 2
Output Data
Step1이 오류없이 정상적으로 제출 되었다면 documnt_fields, missing_fields, reviewOCRData, SubmissionId, idImage를 결과 값으로 확인할 수 있습니다.
document_fields에는 신분증에서 확인할 수 있는 데이터들, missing_fields에는 신분증에 데이터가 존재하지만 읽어오지 못한 데이터들, reviewOCRData에는 신분증에서 추출된 데이터들을 확인할 수 있습니다.
Submissionid
submission의 ID. *해당 ID는 step1 재시도와 step 2에서 필요합니다.
reviewOCRData
신분증 정보를 포함하는 OCR 오브젝트. 만약 OCR 인식에 실패하면 이 파라미터는 반환되지 않음.
reviewOCRData.ocr_birthDate
YYYY-MM-DD 형식의 생년월일
reviewOCRData.accepted_ocr_birthDate
생년월일 인식 성공 여부 (true/false)
reviewOCRData.ocr_issueDate
발급 일자
reviewOCRData.accepted_ocr_issueDate
발급 일자 인식 성공 여부 (true/false)
reviewOCRData.ocr_expireDate
만료 일자 (이용 가능할 때)
reviewOCRData.accepted_ocr_expireDate
만료 일자 인식 성공 여부 (true/false)
reviewOCRData.ocr_lastName
성
reviewOCRData.accepted_ocr_lastName
성(last name) 인식 성공 여부 (true/false)
reviewOCRData.ocr_firstName
이름
reviewOCRData.accepted_ocr_firstName
이름(frist name) 인식 성공 여부 (true/false)
reviewOCRData.ocr_name
전체 이름
reviewOCRData.accepted_ocr_name
이름 인식 성공여부 (true/false)
reviewOCRData.ocr_gender
성별
reviewOCRData.accepted_ocr_gender
성별 인식 성공여부 (true/false)
reviewOCRData.ocr_nationality
ISO3 코드 형식의 국가코드
reviewOCRData.accepted_ocr_nationality
국적 인식 성공여부 (true/false)
reviewOCRData.ocr_identityNumber
사용자 고유의 식별번호
reviewOCRData.accepted_ocr_identityNumber
사용자 고유 식별번호 인식 성공여부 (true/false)
reviewOCRData.ocr_licenseNumber
운전면허번호(한국 only)
reviewOCRData.accepted_ocr_licenseNumber
운전면허번호 인식 성공여부 (true/false)
idImage
신분증 앞면 사진 경로
idBackImage
신분증 뒷면 사진 경로
file_upload
신분증 사진이 성공적으로 받아졌으면 “true”, 그렇지 않을 때는 “fail”
file_back_upload
신분증 뒷면 사진이 성공적으로 받아졌으면 “true”, 실패 시 “fail”
document_fields
아래의 항목이 인식된 신분증에 존재하는지 여부 documentnumber, expireDate, gender, identityNumber, issueDate, nationality: true/false 1) Universal Mode 사용 시, OCR 인식 실패 시 Array 형태 2) 그 외, 단일 Object 형태
document_fields.expireDate
true/false
document_fields.idNumber
true/false
document_fields.identityNumber
true/false
document_fields.gender
true/false
document_fields.issueDate
true/false
document_fields.nationality
true/false
document_fields.number
true/false
document_fields.name
true/false
document_fields.birthDate
true/false
document_fields.serialNumber
true/false
document_fields.documentNumber
true/false
missing_fields
인식된 신분증에 있어야 하지만 OCR인식 실패로 읽지 못한 항목 예시) [gender, documentNumber, identityNumber]
retry
kycStatus가 ‘incomplete”인 경우에, 재시도 사유를 retryCode와 retryMsg로 보여줍니다.
kycStatus
<pending, approved, rejected, incomplete> 'incomplete'는 불충분한 KYC 데이터로 인해 제출이 완료되지 못한 상태입니다. 셀피 제출 단계에서 총 3번의 기회가 주어집니다.
retryCount
Step 1의 재시도 횟수. Step 1 시도 횟수가 3회가 되면 KYC는 자동으로 거절됩니다.
Sample Response
Retry & Error Codes
Retry code와 error code는 Retry/Error/Reject Codes 페이지에서 확인해 주세요.
Step 1 Sample
Request URL
Sample Request
Sample Response
주의사항
OCR 텍스트 추출이 원활하게 되기 위해서는 이미지에 사각형의 신분증이 존재한 다는 것을 알 수 있도록 약간의 여백이 필요합니다. 신분증의 네 모서리를 타이트하게 잘라 제출하면 OCR 추출 결과물이 없을 수 있습니다.
신분증별 뒷면 수집 여부
STEP1 단계에서'ID Card Back' 열이 'TRUE'인 신분증은 뒷면을 수집합니다. 저장 여부는 신분증 상세 종류에 따라 달라질 수 있습니다. 자세한 내용은 'Input Data' 영역의 첨부파일을 확인해주세요.
Last updated