REST API 본인인증

REST API 본인인증은 PG 인증창 대신 가맹점이 직접 만든 화면​​으로 본인인증을 진행하는 방식이에요. 서버가 SMS OTP 발송(요청) → 재전송 → OTP 검증(승인)을 단계별로 호출해요.

자체 디자인의 입력 폼이 필요하거나 인증 흐름을 서버에서 통제해야 할 때 사용해요. 일반적인 경우에는 SDK 본인인증이 더 간단해요.

흐름

모든 호출은 서버에서 Basic Auth로 인증해요.

1본인인증 요청

curl -X POST "https://api.bootpay.co.kr/v2/request/authentication" \
  -H "Authorization: Basic $(printf '%s' 'CLIENT_KEY:SECRET_KEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "pg": "다날",
    "method": "본인인증",
    "order_name": "회원가입 본인확인",
    "authentication_id": "auth_1700000000",
    "username": "홍길동",
    "identity_no": "9112121",
    "phone": "01012345678",
    "carrier": "SKT",
    "authenticate_type": "sms",
    "client_ip": "123.123.123.123"
  }'bash

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

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

const response = await Bootpay.requestAuthentication({
    pg: '다날',
    method: '본인인증',
    order_name: '회원가입 본인확인',
    authentication_id: 'auth_' + Date.now(),
    username: '홍길동',
    identity_no: '9112121',      // 생년월일 6자리 + 주민번호 뒤 1자리
    phone: '01012345678',
    carrier: 'SKT',
    authenticate_type: 'sms',    // sms | pass
    client_ip: req.ip,
})

// response.receipt_id 를 세션/DB에 저장 → 승인 단계에서 사용
console.log(response.receipt_id, response.status) // status 51: 승인 대기javascript

응답 예시

{
  "receipt_id": "636375501fc19203724b3ad8",
  "authentication_id": "1667462479",
  "metadata": {},
  "pg": "다날",
  "method": "인증",
  "method_symbol": "auth",
  "method_origin": "인증",
  "method_origin_symbol": "auth",
  "requested_at": "2026-04-03T17:01:20+09:00",
  "status": 51,
  "authenticate_data": {
    "tid": "202211031701204002337011",
    "number_of_realarms": 0
  }
}json

status: 51은 SMS/PASS 발송이 끝나고 OTP 승인을 기다리는 상태예요. receipt_id를 보관했다가 승인 단계에서 사용해요. 51은 상태 한글 라벨이 정의돼 있지 않아 status_locale 키 자체가 응답에서 빠져요.

2SMS 재전송 (선택)

사용자가 OTP 문자를 받지 못한 경우 같은 receipt_id로 재전송해요. number_of_realarms로 재전송 횟수를 확인할 수 있어요.

curl -X POST "https://api.bootpay.co.kr/v2/authenticate/realarm" \
  -H "Authorization: Basic $(printf '%s' 'CLIENT_KEY:SECRET_KEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{ "receipt_id": "RECEIPT_ID" }'bash

const response = await Bootpay.realarmAuthentication(receiptId)
console.log(response.authenticate_data.number_of_realarms) // 재전송 횟수javascript

3본인인증 승인

사용자가 입력한 OTP로 인증을 확정해요. 성공하면 authenticate_data(이름·CI/DI 등)를 받아요.

curl -X POST "https://api.bootpay.co.kr/v2/authenticate/confirm" \
  -H "Authorization: Basic $(printf '%s' 'CLIENT_KEY:SECRET_KEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{ "receipt_id": "RECEIPT_ID", "otp": "123456" }'bash

// SMS 방식: 사용자가 입력한 OTP 6자리 전달 / PASS 방식: null
const result = await Bootpay.confirmAuthentication(receiptId, otp)

if (result.status === 12) {
    const { name, birth, gender, foreigner, carrier, unique, di } = result.authenticate_data
    // CI(unique)·DI(di)는 암호화 저장
    await saveVerifiedUser({ name, birth, gender, ci: encrypt(unique), di: encrypt(di) })
}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:07:58+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

에러 코드

다음 단계

• 인증창 UI를 PG에 맡기는 더 간단한 방식은 SDK 본인인증을 확인해요.
• 결과값(CI/DI) 저장 설계는 데이터 모델 설계를 참고해요.