POST/Submission/Step2

Request URL

curl -X POST "https://rest-api.argoskyc.com/v3/submission/step2"
-H "x-api-key: {yourAPIKey}"
-form ...

• Step2에서는 Step1에서 추출된 데이터를 토대로 입력 데이터를 작성하여 제출합니다.

• Step2는 얼굴 비교, 신분증에서 추출된 데이터와 사용자 입력 데이터 비교, 주소지 수집 및 증명 등을 진행하는 단계입니다.

• Step2는 form-data 형식으로 제출해야 합니다.

• Step2에서는 얼굴사진을 총 3번(처음 1번 + retry 2) 보낼 수 있습니다. Step 2의 첫 번째 시도가 진행되었다면, Step 1 시작 지점부터 24시간 내에 KYC 제출이 완료되어야 합니다. (Step2 진행 이력이 있지만 KYC 결과가 나지 않은 submission은 24시간 후 Reject 됩니다.)

• 제출된 Submission의 상세 정보는 대시보드, 또는 Get submission API로 확인 할 수 있습니다.

• 주소지 수집 옵션이 설정되어 있으면 globalCode, compoundCode, formatted_address, address_input, address_detail 값을 요구합니다. 해당 값을 구하기 위해 POST/Address_code API를 사용합니다. globalCode, compoundCode, formatted_address 값 중 하나는 반드시 있어야 합니다.

• address_input은 사용자가 직접 입력한 주소 address_detail은 상세주소를 나타냅니다. 필수로 요구하는 값은 아닙니다.

• Step1에서 생성된 Submission ID를 Step2에서 반드시 입력 해야 합니다.

• SubmissionId, faceimage, name, date_of_birth 입력 데이터를 필수로 요구합니다.

• Retry code와 error code는 Retry/Error/Reject Codes 페이지에서 확인해 주세요.

• faceImage의 표준 권장 사양은 960 x 720 픽셀 입니다.

Input Data

*이 붙은 것은 필수 파라미터 입니다.

파라미터	타입	설명
*submissionId	string	step 1으로 받은 제출된 고유 ID
*faceImage	file	하나의 얼굴을 보여주는 셀피 사진. 여러 명의 얼굴이 감지되면 재시도로 응답. (권장 용량: 1mb, 최대: 2mb)
*name	string	First Name Last Name을 구분하지 않은 Fullname(First_Name & Last_Name)의 형태
*date_of_birth	string	YYYY-MM-DD
gender	string	<male, female>
nationality	string	ISO alpha 3 형식의 국적
identity_number	string	사용자 고유의 식별번호
license_number	string	한국 운전면허증의 면허번호 12자리 12자리 숫자(12-34-567890-12 ) or 지역명과 10자리 숫자(서울-12-345678-90)
document_number	string	문서 고유번호 (여권번호, 해외 운전면허 번호 등)
serial_number	string	한국 운전면허증의 고유한 6자리 일련번호
date_of_issue	string	YYYY-MM-DD 형식의 신분증 발급일자
date_of_expiry	string	YYYY-MM-DD 형식의 신분증 만일자
addressImage	file	주소지 증명 문서 사진 파일 (권장 용량: 1mb, 최대: 2mb)
address_street	string	도로 주소
address_city	string	도시
address_state	string	주
address_country	string	ISO 3 형식의 국가코드
address_zipcode	string	우편번호
globalCode	string	전체 주소에 대한 상세 코드 값 (예. 8Q98HX4FvmfRC)
compoundCode	string	국가 및 도시와 상세주소 코드 값 (예. HX4F+RC Seoul, South Korea)
formatted_address	string	정형화된 주소 값
address_input	string	사용자 입력 주소 값 (사용자가 직접 주소를 입력하고 싶은 경우 사용)
address_detail	string	사용자 입력 상세 주소 값 (건물 이름만 있을 때 정확한 주소를 기재하기 위해 사용)
userOccupancyCode	string	PreStep2(1원 계좌 인증)을 진행한 경우, 1원 입금 시 받은 인증 코드 3자리 (ex. 123테스트)
userOccupancyName	string	PreStep2(1원 계좌 인증)을 진행한 경우, 1원 입금 시 받은 예금주 성명
idType	string	(Universal mode 옵션 사용 시) Step1 에서 OCR 인식 실패로 idType 이 ‘any’ 로 반환 된 경우, Step2 진행 시 idType 을 필수 제출 유효한 값 : passport, government_id, drivers_license, residence_permit, vehicle_registration certificate, visa, aadhaar, pancard

진위확인 Input Data

진위 확인은 신분증의 발급 국가와 신분증 타입에 따라 필요한 파라미터가 달라집니다.

Issuing Country	ID Type	Required Parameters
KOR	government_id	name, date_of_birth, identity_number
KOR	drivers_license	date_of_birth, license_number, serial_number
KOR	passport	name, date_of_birth, document_number, date_of_issue, date_of_expiry
KOR	residence permit	identitiy_number, date_of_issue
USA, CAN, MEX	drivers_license	name, date_of_birth, gender, date_of_expiry, date_of_issue, dcoument_number

Sample Request 1

curl --location --request POST 'https://rest-api.argoskyc.com/v3/submission/step2' \
--header 'x-api-key: {YOUR_API_KEY}' \
--form 'faceImage=@"/C:/Users/face.jpg"' \
--form 'name="홍길동"' \
--form 'nationality="KOR"' \
--form 'date_of_birth="1998-11-11"' \
--form 'date_of_issue="2016-11-11"' \
--form 'submissionId="d76h19l46m****"' \
--form 'identity_number="981112-1******"' \
--form 'gender="male"'

Sample Request 2

var myHeaders = new Headers();
myHeaders.append("x-api-key", "{YOUR_API_KEY}");

var formdata = new FormData();
formdata.append("faceImage", fileInput.files[0], "/C:/Users/face.jpg");
formdata.append("name", "홍길동");
formdata.append("nationality", "KOR");
formdata.append("date_of_birth", "1998-11-11");
formdata.append("date_of_issue", "2016-11-11");
formdata.append("submissionId", "d76h19l46m****");
formdata.append("identity_number", "981112-1******");
formdata.append("gender", "male");

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: formdata,
  redirect: 'follow'
};

fetch("https://rest-api.argoskyc.com/v3/submission/step2", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Output Data

응답	설명
kycStatus	<pending, approved, rejected, incomplete> Pending: KYC 제출 완료 후 수동 검수 Icomplete: 부족한 KYC 데이터로 인해 제출이 완료되지 않음 *kycStatus가 ‘pending’, ‘approved’나 ‘rejected’ 상태로 변할때까지 step 2의 재시도를 하길 추천
faceSimilarityScore	신분증의 사진과 셀카 사진의 얼굴 유사도 점수, 100에 가까울수록 두 얼굴이 일치할 확률이 커짐(0~100).
livenessScore	셀피 이미지 속 얼굴이 실제 인물인지 여부를 평가하며, 점수가 100에 가까울수록 이미지는 (영상이나 이미지의 이미지가 아닌)실제 인물 사진일 가능성이 높아짐(0~100).
verificationResult	<success, fail>
retryCount	Step 재시도 횟수, 2번을 넘을 경우 KYC는 거절됨.
retry	kycStatus가 ‘incomplete'인 경우에, 재시도 사유를 retry code와 retry message로 보여줌.
recognized_IdType	Universal mode 사용 시, Step1 에서 OCR 인식 성공 한 경우 정의된 idType

Sample Response - Approved

{
    "faceSimilarityScore": 99,
    "livenessScore": 74,
    "kycStatus": "approved",
    "retryCount": 0
}

Sample Response - Rejected

{
    "livenessScore": 74,
    "kycStatus": "rejected",
    "retryCount": 3
}

Sample Response - Pending

{
    "faceSimilarityScore": 99,
    "livenessScore": 74,
    "kycStatus": "pending",
    "retryCount": 0
}

Sample Response - Incomplete

{
    "retry": [
        {
            "retryCode": "face_compare_fail",
            "retryMsg": "Face compare failed: no matching face"
        }
    ],
    "kycStatus": "incomplete",
    "retryCount": 1
}

Retry & Error Codes

• Retry code와 error code는 Retry/Error/Reject Codes 페이지에서 확인해 주세요.

주의사항

얼굴 비교가 원활하게 되기 위해서는 셀피 이미지에서 얼굴의 비율이 적절해야 합니다. 전체 이미지에서 얼굴이 차지하는 비율이 너무 크거나, 너무 작으면 얼굴 비교에 실패할 수 있습니다. 아래의 이미지 아르고스 라이브폼에서 사용하는 가이드 라인과 적절한 비율의 얼굴 사진, 적절하지 못한 비율의 얼굴 사진 예시입니다.