SDK 본인인증

SDK 본인인증은 프론트엔드에서 requestAuthentication()을 호출하면 PG가 제공하는 인증창(통신사 선택·OTP 입력)을 띄우고, 인증이 끝나면 receipt_id를 돌려주는 방식이에요. 가장 일반적인 본인인증 연동이에요.

이후 서버에서 그 receipt_id로 결과를 조회해 이름·CI/DI 같은 값을 확정해요.

핵심 요약

• 프론트엔드 requestAuthentication() → 인증창 표시 → done 이벤트로 receipt_id 수신
• receipt_id를 서버로 보내 GET /v2/certificate/{receipt_id}로 결과를 다시 조회
• 조회 응답의 authenticate_data(이름·CI/DI 등)를 검증한 뒤 회원·주문 흐름에 반영
• 프론트엔드 결과만 믿고 실명·성인 여부를 확정하지 않아요

1인증창 호출 (프론트엔드)

import { Bootpay } from '@bootpay/client-js'

async function requestAuthentication() {
    try {
        const response = await Bootpay.requestAuthentication({
            client_key: '[ Client Key ]',
            pg: '다날',
            order_name: '본인인증',                        // 인증창에 표시될 이름
            authentication_id: 'auth_' + Date.now(),       // 가맹점이 부여하는 고유 본인인증 ID
            user: {
                username: '홍길동',     // 선입력 시 사용자가 다시 입력하지 않아도 됨 (선택)
                phone: '01012345678'
            }
        })

        // 인증 완료 → receipt_id를 서버로 보내 결과를 확정
        if (response.event === 'done') {
            await confirmIdentity(response.data.receipt_id)
        }
    } catch (e) {
        console.log(e.message)   // 사용자가 인증창을 닫거나 인증에 실패한 경우
    }
}

async function confirmIdentity(receiptId) {
    await fetch('/api/identity/confirm', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ receipt_id: receiptId })
    })
}javascript

요청 파라미터

인증 완료 이벤트 데이터

done 이벤트로 받는 데이터는 결과 조회를 위한 최소 정보​​예요. 실명·CI/DI 같은 값은 들어있지 않으므로 서버 조회가 필요해요.

{
  "event": "done",
  "data": {
    "receipt_id": "624ce9d31fc19202e4746f3b",
    "authentication_id": "1649207763202",
    "gateway_url": "https://gw.bootpay.co.kr",
    "metadata": {},
    "pg": "다날",
    "method": "인증",
    "method_symbol": "auth",
    "method_origin": "인증",
    "method_origin_symbol": "auth",
    "authenticated_at": "2026-04-06T10:16:20+09:00",
    "requested_at": "2026-04-06T10:16:03+09:00",
    "status_locale": "본인인증완료",
    "status": 12
  }
}json

2결과 조회 (서버)

프론트엔드에서 받은 receipt_id로 서버에서 인증 결과를 조회해요. 이 응답의 authenticate_data가 신뢰할 수 있는 최종 결과​​예요.

curl -X GET "https://api.bootpay.co.kr/v2/certificate/RECEIPT_ID" \
  -H "Authorization: Basic $(printf '%s' 'CLIENT_KEY:SECRET_KEY' | base64)"bash

import { Bootpay } from '@bootpay/backend-js'

Bootpay.setConfiguration({
    client_key: process.env.BOOTPAY_CLIENT_KEY,
    secret_key: process.env.BOOTPAY_SECRET_KEY,
})

export async function confirmIdentity(receiptId) {
    const result = await Bootpay.certificate(receiptId)

    if (result.status !== 12) {
        throw new Error('본인인증이 완료되지 않았습니다')
    }

    const { name, birth, gender, foreigner, carrier, unique, di, phone } = result.authenticate_data

    // CI(unique)·DI(di)는 개인정보이므로 암호화하여 저장해요
    await db.users.update({
        verified_name: name,
        verified_birth: birth,
        verified_ci: encrypt(unique),
        verified_di: encrypt(di),
        verified_at: new Date(),
    }, { where: { phone } })

    return result.authenticate_data
}javascript

응답 예시

{
  "receipt_id": "624d2e531fc19202e4746f40",
  "authentication_id": "1649225299700",
  "gateway_url": "https://gw.bootpay.co.kr",
  "metadata": {},
  "pg": "다날",
  "method": "인증",
  "method_symbol": "auth",
  "method_origin": "인증",
  "method_origin_symbol": "auth",
  "authenticated_at": "2026-04-06T15:08:42+09:00",
  "requested_at": "2026-04-06T15:08:19+09:00",
  "status_locale": "본인인증완료",
  "status": 12,
  "authenticate_data": {
    "phone": "01012345678",
    "name": "홍길동",
    "birth": "19911212",
    "gender": 0,
    "foreigner": "0",
    "carrier": "SKT",
    "unique": "[ CI 값 ]",
    "di": "[ DI 값 ]",
    "tid": "202204061508210451927011"
  }
}json

authenticate_data 필드의 의미는 본인인증 개요를 참고해요.

에러 코드

다음 단계

• 인증 화면을 직접 구성하거나 OTP를 단계별로 제어하려면 REST API 본인인증을 확인해요.
• 결과값(CI/DI) 저장 설계는 데이터 모델 설계를 참고해요.