본문으로 건너뛰기
버전: 1.0.0

문서 보고 따라하기

웹 환경에 iframe으로 연동하기

이 페이지에서는 웹(Web) 환경에서 eKYC를 연동하는 방법을 안내합니다.
고객사 서비스 내에서 eKYC 인증 UI를 호출하려면 iframe 방식을 사용해 인증 페이지를 불러와야 합니다.
아래 가이드를 참고해 고객사 서비스에 인증 화면을 자연스럽게 연동해 주세요.

웹에 연동하기 전 필수 세팅: HTML에 iframe 삽입하기​

eKYC 인증 화면은 iframe을 통해 고객사 서비스 내에 임베딩되어 보여지게 돼요.
따라서 인증 요청을 하기 전에, 먼저 HTML에 iframe 태그를 정의해 두어야 해요.
iframe은 인증 요청 후 화면을 띄우는 그릇 역할을 하며,
이 요소가 있어야 인증 페이지가 정상적으로 로드되고 이후 결과도 전달받을 수 있어요.

  • HTML 예제
<iframe
  id="kyc_iframe"
  class="fullscreen bg-white"
  allow="camera"
  src="https://kyc.useb.co.kr/auth"
>
</iframe>
Q. 웹앱 환경에서 카메라가 실행되지 않아요. 어떻게 해야 하나요?

ㄴ A. 웹앱에서는 기본적으로 브라우저의 카메라 권한을 따라갑니다.

  • 고객사 코드 설정 확인
    iframe 태그에 allow="camera" 속성이 추가되어있는지 확인해 주세요. 이 속성이 반드시 있어야 카메라가 실행됩니다.
  • 엔드 유저 기기/브라우저 설정 확인
    1. 사용 중인 브라우저(Chrome, Safari)의 카메라 권한이 허용되어 있는지 확인해 주세요.
    2. iOS Safari 환경에서는 반드시 https 환경에서만 카메라가 동작합니다.
Q. iframe의 id는 꼭 "kyc_iframe"이어야 하나요?

ㄴ A. 예제에서는 "kyc_iframe"으로 지정했지만, 실제 서비스에서는 다른 이름을 써도 돼요.
단, 이후 JavaScript 코드에서 동일한 id로 document.getElementById("...")를 통해 참조하므로, id 값은 반드시 HTML과 JS에서 일치해야 해요.

Q. iframe은 꼭 이렇게 생겨야 하나요? (id, class, allow, src 전부 필수인가요?)

ㄴ A. 꼭 전부 필수는 아니지만, 대부분의 경우 아래 항목들은 권장합니다:

  • id: JavaScript에서 해당 iframe을 조작하려면 반드시 필요해요 (document.getElementById()로 찾음)
  • allow="camera": 카메라를 사용하는 인증 방식이라면 반드시 필요해요
  • src: 인증 화면을 띄우려면 반드시 URL이 지정돼야 해요
  • class: TailwindCSS를 쓰는 경우 스타일용. 없애도 동작에는 문제 없어요 (단, 기본 높이나 배경은 지정 필요)
Q. 우리 서비스가 PHP, JSP인데 React 예제처럼 사용해도 되나요?

ㄴ A. 네, iframe은 HTML 기반 요소이기 때문에, 프레임워크에 관계없이 JSP, PHP, HTML 어디서든 동일하게 사용 가능해요.
단, 결과 수신을 위한 postMessage 처리 코드는 별도 <script> 로 삽입해주세요.
PHP/JSP 파일에서도 <script> 블록은 클라이언트에서 실행돼요.

1단계. 인증 방식 정하기​

고객사에서 유스비 eKYC 서버에 접근하기 위해서는 유스비의 고객사라는 것을 먼저 인증해야 해요.
이 때 인증하는 방식은 토큰 없이도 인증이 가능한 Credential과 토큰 발급이 필수적인 Access Token이 있어요. 고객사마다 각자의 보안 및 운영 목적에 맞는 방식을 선택해 인증을 진행하면 돼요.

  • Credential → 테스트/PoC 용
  • Access Token → 보편적인 운영용

1. Credential​

메일로 전달받은 customer_id, id, key 값을 요청에 그대로 사용해요.
구조가 단순하지만 보안상 노출 위험이 있어 이 방식은 실제 운영 전 테스트, PoC 용도로 한정해 사용하는 것을 권장해요.

2. Access Token 방식​

서버 또는 클라이언트에서 Access Token을 먼저 발급받고, 해당 토큰으로 인증 요청을 보내요.
이 방식은 보안이 더 강하고, 토큰은 24시간 동안 유효해요.
Access Token을 발급 받으려면, 아래의 정보로 API를 조회하면 돼요.

Access Token 발급을 위한 API 조회 방법 확인하기

Request Body:

  • [POST] https://kyc-api.useb.co.kr/sign-in 
{
    "customer_id": <customer_id>,   //number, 고객사id
    "username": "<id>",             //string, client_id
    "password": "<key>"             //string, client_secret
}

Response

{
    "api_response": {
        "result_code": "N100",
        "result_message": "OK."
    },
    "company": {
        "name": "id",
        "industry": 2,
        "phone_number": "1500-0002"
    },
    "expire": "2022-08-17T11:10:29Z",  // 생성 후 24시간 뒤에 만료됨
    "is_temp_password": true,
    "name": "",
    "role": 2,
    "token": "**<access_token>**",     // **Access Token** 획득
    "username": "<client_id>"
}

2단계. 요청 보내기​

HTML에 iframe을 세팅했고, 인증 방식을 정했다면 이제 요청을 보낼 차례예요.
이 단계에서는 리스너 등록부터 조건에 맞는 요청을 보낼 때 고려해야하는 항목들을 정해 eKYC 인증 화면을 요청하는 절차까지 진행할 거예요.
요청을 보낼 때는 다음 항목들을 정해 두어야 해요.

  • 인증 방식 (Credential / Access Token)
  • 필수 정보 입력 방식 (고객사 자체 구현 (파라미터 전달, Transaction_id (심사 사전 등록) 전달)/ 유스비 제공 화면 사용)
  • 다국어(영문) 지원 및 폰트 적용 여부

1. 리스너 등록하기​

eKYC 인증이 완료되면, 결과는 postMessage를 통해 iframe을 띄운 고객사 페이지로 전달돼요.
이때, 결과 메시지를 놓치지 않고 받으려면 브라우저의 window에 리스너가 등록되어 있어야 해요.

  • 리스너 등록 예제 확인하기
    ⚠️ 예제는 요청 보내는 전체 소스의 일부만 예시로 제공하는 것이니 참고용으로 활용해 주세요.

    window.addEventListener("message", (e) => {
      console.log("alcherakyc response", e.data); // base64 encoded된 JSON 메시지이므로 decoded해야 함(needs to be decoded becaused it`s encoded by base64)
      console.log("origin :", e.origin);
      try {
        const decodedData = decodeURIComponent(atob(e.data));
        console.log("decoded", decodedData);
        const json = JSON.parse(decodedData);
        console.log("json", json);

        // 데이터처리 부분
        // UI 처리
      } catch (error) {
        console.log("wrong data", error);
      }
    });
Q. 리스너는 언제 등록해야 하나요?

ㄴ A. 인증 요청을 보내기 전에 등록해야 해요. 리스너가 먼저 준비되어 있어야 결과 메시지를 받을 수 있어요.

Q. 리스너가 등록되어 있는데 결과를 못 받아요. 왜 그런가요?

ㄴ A. iframe이 제대로 로드되지 않았거나, postMessage를 보낸 쪽과 받은 쪽의 origin이 다를 수 있어요. 콘솔 로그로 origin 값을 꼭 확인해 주세요.

Q. 메시지를 디코딩할 때 오류가 나요. 어떤 문제일까요?

ㄴ A. e.data는 base64 + URI 인코딩 형식이라서, 반드시 decodeURIComponent(atob(...)) 순서로 처리해야 해요.

2. 파라미터 조건 채우기​

1) 인증 방식에 따른 인증 값 넣어주기 (필수)​

1단계에서 미리 인증 방식을 결정한 상태이므로, 요청을 보내는 시점에서는 인증 방식에 따른 인증 값을 전달하면 돼요.

  • Credential: 계정 정보 3가지 customer_id , id, key
  • Access Token: Access Token

2) 필수 정보 입력 방식 정하기 (필수)​

(1) 고객사 자체 구현
고객사에서 직접 구현한 화면을 통해 엔드 유저의 필수 정보를 입력받는 경우예요.
이 경우, 요청 시 엔드 유저에게서 받은 정보를 반드시 파라미터로 전달해 주셔야 해요.
이 때, 정보를 파라미터로 직접 전달하거나 심사 사전 등록 방식을 통해 transaction_id 로 전달할 수도 있어요.

  • 파라미터 전달 방식

  • Transaction (심사 사전 등록) 방식

    Transaction (심사 사전 등록) 방식으로 전달하기

    eKYC 인증을 위해 엔드 유저의 필수 개인 정보를 고객사에서 직접 수집하는 경우, 해당 정보를 전달하는 과정에 보안을 강화할 수 있는 인증 방식이에요. Access Token으로 먼저 인증 정보를 서버에 등록하고, 받은 transaction_id로 인증을 진행해요.

    인증 요청 전에 정보를 서버에서 설정하기 때문에 클라이언트에 민감한 정보가 노출되지 않아 보안적으로 더 안전해요. 이 방식은 Access Token을 먼저 발급받은 후 /verifications API를 통해 사용할 수 있어요. Transaction_id를 발급 받으려면, 아래의 정보로 API를 조회하면 돼요.

    Transaction_id 발급을 위한 API 조회 방법 확인하기

    API 조회 바로가기

    Request Body:

    • [POST] https://kyc-api.useb.co.kr/verfications 
    {
    "name": "홍길동",
    "birthday": "1981-11-23",
    "phone_number": "01012345678",
    "email": "test@test.com"
    }

    Response

    {
      "form": {
        "transaction_id": "1754035720510123456-6126383872156123456",
        "progress": {
          "is_id_card_checked": false,
          "is_account_checked": false,
          "is_face_checked": null,
          "is_custom_field_checked": null,
          "is_edd_field_checked": null
        },
        "module": {
          "id_card_ocr": true,
          "id_card_verification": true,
          "face_authentication": false,
          "account_verification": true,
          "liveness": false,
          "custom_field": false,
          "edd_field": false
        }
      },
      "api_response": {
        "result_code": "N100",
        "result_message": "OK."
      }
    }

(2) 유스비 화면 사용
유스비 eKYC 인증 화면에서 엔드 유저 정보를 입력받도록 위임하는 경우예요.
이 경우, 유스비 Admin에서 설정을 변경해 주어야 해요.
설정 위치: Admin > 기타 설정 > 개인정보 옵션에서 [사용자 필수 정보 수신]을 미사용으로 선택해 주세요.

3) 다국어 (영문) 지원 및 폰트 적용 여부 (선택)​

다국어(영문) 지원과 폰트 (나눔 고딕) 적용 여부를 선택할 수 있어요.
별도로 파라미터를 전달하지 않으면, 기본 설정값은 한국어, Pretendard로 적용하여 제공돼요.

3. 요청 코드 예제​

아래 코드는 Access Token + 자체 구현 + 다국어 On + 폰트 On 조건일 때의 파라미터 예제예요.

const KYC_TARGET_ORIGIN = "https://kyc.useb.co.kr";
const KYC_URL = "https://kyc.useb.co.kr/auth";
const params = {
  access_token: "<access_token>",
  name: "홍길동",
  birthday: "1984-11-23",
  phone_number: "01012345678",
  email: "test@test.com",
  font: "Nanum Gothic", // 폰트명 (Noto Serif KR | Nanum Gothic) (default: pretendard)
  language: "en", // 영어 지원 (en) (default : 한국어)
};

고객사별 상황에 딱 맞는 예제는 다음 페이지인 ‘예제로 바로 적용하기’에서 만들어 볼 수 있어요.

4. 인코딩 규칙​

파라미터 전달 시 “JSON → URI 인코딩 → Base64” 순서를 유지하고,
수신 시에는 “Base64 → URI 디코딩 → JSON 파싱” 순서를 지켜야 해요.

const KYC_TARGET_ORIGIN = "https://kyc.useb.co.kr";
const KYC_URL = "https://kyc.useb.co.kr/auth";
const params = {
  access_token: "<access_token>",
  name: "홍길동",
  birthday: "1984-11-23",
  phone_number: "01012345678",
  email: "test@test.com",
};
const encodedParams = btoa(encodeURIComponent(JSON.stringify(params)));

3단계. 결과 받아 처리하기​

1. 결과 데이터 파싱​

웹 페이지에서 window.addEventListener("message")를 통해 결과를 수신해요.
이때 전달되는 데이터는 Base64 + URI 인코딩된 JSON 문자열이에요.
따라서 Base64 디코딩 → URI 디코딩 → JSON 파싱 순서로 처리해야 해요.

window.addEventListener("message", (e) => {
    console.log("alcherakyc response", e.data); // base64 encoded된 JSON 메시지이므로 decoded해야 함(needs to be decoded becaused it`s encoded by base64)
    console.log("origin :", e.origin);
    try {
        const decodedData = decodeURIComponent(atob(e.data));
        console.log("decoded", decodedData);
        const json = JSON.parse(decodedData);
        console.log("json", json);

2. 결과 수신 방식​

eKYC 인증 결과를 수신하는 방식은 두 가지 중 선택할 수 있어요.

1) postMessage

postMessage 방식은 결과 메시지를 프론트에서 그대로 받아서 처리하는 방식이에요.

2) postMessage + API

postMessage + API 방식은 postMessage에서 전달받은 일부 값(id, result_type)을 바탕으로 서버에서 전체 결과를 조회해요.
API 방식은 보안을 강화할 수 있지만 아래와 같은 절차를 추가로 진행해야 해요.

  1. 유스비 담당자에게 문의하여 reviewer account 를 받아야 해요.
  2. reviewer account로 전달받은 customer_id , username , password 로 API를 조회하여 결과 수신용 Access Token을 취득해요.
• 결과 수신용 Access Token 취득하기
  • swagger 에서 하기 API를 활용하여 Access Token을 취득합니다.
    • [POST] https://kyc-api-swagger.useb.co.kr/

      Request

      {
      "customer_id": 1,
      "username": "samsungAdmin",
      "password": "password123!"
      }

      Response

      {
      "company": {
          "name": "samsung",
          "industry": 1,
          "phone_number": "1500-0000"
      },
      "role": 1,
      "name": "samsung_reviewer",
      "username": "Reviewer0001",
      "is_temp_password": true,
      "token": "<token>",
      "expire": "2022-01-06T11:41:42+09:00",
      "api_response": {
          "result_code": "N100",
          "result_message": "OK."
      }
      }

    1. 취득한 Access Token과 postMessage 값 중 id , result_type 을 활용해 API를 호출해요.
    • 서버에 API 호출해 전체 결과 받아오기

    취득한 Access Token은 HTTP 요청의 Authorization 헤더에 적용해 주세요.
    아래 내용을 확인해 result_type 에 해당하는 API를 호출하면 전체 결과를 확인할 수 있어요.
    1: Automatic approval (자동승인대상)
    2 : Automatic rejection (자동거부대상)
    5 :Manual review target (수동심사대상)

    • result_type = 1, "auto_approve" / result_type = 2, "auto_reject"
    • [GET] https://kyc-api.useb.co.kr/review/results/{id}
      • "auto_approve" : 3회 안에 진위확인 성공시
      • "auto_reject" : 3회 진위확인 실패시
    • result_type = 5, "wait_review"
      • [GET] https://kyc-api.useb.co.kr/review/manuals/{id}
      • OCR 판독 후에 개인정보를 수정한 경우, 사본으로 판별된 경우 등등
      • 수동심사 대상인 경우에도 마지막 화면의 문구 변경은 가능합니다.
    • get attachment file (EDD 강화된 고객확인 서비스 사용시)
      • [GET] https://kyc-api.useb.co.kr/attachments/{id}

    3. 결과 처리 예제​

    파싱된 JSON의 result 값에 따라 분기 처리하시면 돼요. 예제는 콘솔 출력이지만, 실제 서비스에서는 화면 전환/알림/재시도/서버 검증 등 비즈니스 로직으로 연결하세요.

    window.addEventListener("message", (e) => {
      console.log("alcherakyc response", e.data); // base64 encoded된 JSON 메시지이므로 decoded해야 함(needs to be decoded becaused it`s encoded by base64)
      console.log("origin :", e.origin);
      try {
        const decodedData = decodeURIComponent(atob(e.data));
        console.log("decoded", decodedData);
        const json = JSON.parse(decodedData);
        console.log("json", json);

        // 데이터처리 부분
        if (json.result === "success") {
          // TODO: KYC 인증을 성공한 경우 데이터 처리
          // console.log(json.result + "결과 서버 저장");
        } else if (json.result === "failed") {
          // TODO: KYC 인증을 실패한 경우 데이터 처리
          // console.log(json.result + "결과 서버 저장");
        }

        // UI 처리
        else if (json.result === "complete") {
          // TODO: KYC 인증을 성공(자동승인 or 심사필요 케이스 모두 포함) 후 UI 처리
          // iframe이 포함된 UI를 종료
          // 고객사 서비스 UI를 다시 띄우고 상황에 맞는 UI 표시
          // 예시 : 자동승인 -> KYC인증이 완료되었습니다. 계좌개설이 완료되었습니다.
          // 예시 : 심사필요 -> KYC인증이 완료되었습니다. 심사가 완료된 이후 이메일로 안내 드리겠습니다.
        } else if (json.result === "close") {
          // TODO: KYC 인증을 실패(자동거부 or 중도이탈) 후 UI 처리
          // iframe이 포함된 UI를 종료
          // 고객사 서비스 UI를 다시 띄우고 상황에 맞는 UI 표시
          // 예시 : 자동거부 -> KYC인증이 실패하였습니다. 다시 인증을 시도후 서비스 이용이 가능합니다.
        } else {
          // invalid result
        }
      } catch (error) {
        console.log("wrong data", error);
      }
    });
    Q. postMessage로 받은 결과가 어떤 형식인지 모르겠어요.

    ㄴ A. base64로 인코딩된 JSON 문자열이에요. 디코딩 후 JSON으로 파싱해야 실제 데이터를 볼 수 있어요.

    Q. 결과 값 중 complete나 close는 어떤 의미인가요?

    ㄴ A. complete는 인증은 완료되었지만 심사 중인 상태이고, close는 인증이 중단되었거나 자동 거부된 상태예요.

    Q. 보안 강화를 위해 결과를 서버에서 받아올 수 있나요?

    ㄴ A. 네. postMessage로 받은 id와 result_type을 이용해 API로 전체 결과를 조회할 수 있어요. 단, 서버에서 결과를 받으려면, 유스비 담당자에게 직접 문의해 reviewer 계정을 받아서 진행해야 해요.

    Q. postMessage에 개인정보가 오는 게 보안상 이슈가 될 것 같아요.

    ㄴ A. Admin에서 기타 설정 > 보안 설정 > [인증 결과 전송]을 ‘개인정보 미포함’으로 설정을 변경해야 postMessage에서 개인정보를 제외한 결과가 제공돼요. 이 경우, 엔드 유저의 개인정보를 API 호출을 통해 받아와야 하며, 자세한 방법은 이 문서의 3단계에 안내되어있는 postMessage + API 방식을 참고해 주세요.

    연동 완료​

    정상적으로 인증 화면을 띄우고, 결과를 받아 처리했다면 연동이 잘 완료된 거예요.
    운영 환경에 반영하기 전에 테스트 환경에서 브라우저별로 동작을 꼭 확인해 주세요.

    • QA 체크리스트

      Q. 연동 테스트는 어떤 환경에서 해보는 게 좋나요?

      ㄴ A. Chrome, Safari, 삼성 브라우저, 주요 인앱 브라우저 등 iframe이 지원되는 환경에서 테스트해 보세요.

      Q. 인증 요청은 보냈는데 결과가 안 와요. 어디서 문제를 확인해야 하나요?

      ㄴ A. 리스너가 등록되어 있는지, postMessage 수신이 정상적으로 동작하는지, 파라미터 값이 올바른지 순서대로 점검해 보세요.

    더 궁금한 내용이 있나요?에러 코드 및 대응
    코드 샘플을 참고하세요eKYC Github
    기술지원이 필요하신가요?이메일 보내기