토스 인증

Appearance

마지막 작성자: hyejung-song
최근 업데이트: 26. 3. 17. 오후 6:04

본인확인 ​

이 문서에서는 표준창, 앱 푸시, 앱스킴 세 가지 방식으로 본인확인 서비스를 연동하고, 발급부터 결과조회까지 각 단계에서 필요한 API를 호출하는 방법을 안내합니다.

본인확인 서비스는 고객이 입력한 개인정보를 토스 정보와 대조하고 토스 앱 인증으로 신원을 확인합니다. 회원가입, 계정 조회 등 CI/DI가 필요한 서비스에서 휴대폰 본인확인을 대체할 수 있습니다.

CI/DI란?

  • CI (연계정보): 한 사람을 여러 서비스에서 동일하게 식별하는 고유 코드입니다.
  • DI (중복가입확인정보): 동일인의 중복 가입 여부를 확인하는 코드로, 서비스마다 다른 값이 발급됩니다.

사전 준비 ​

연동 전 아래 항목을 먼저 확인하세요.

연동 흐름 ​

표준창 방식 (USER_NONE) ​

고객이 토스 표준창에서 직접 개인정보를 입력합니다. 가장 보편적인 방식입니다.

앱 푸시 방식 (USER_PERSONAL + PUSH) ​

고객사가 개인정보를 암호화해서 전달하면 토스가 고객 앱으로 직접 푸시를 보냅니다.

앱스킴 방식 (USER_PERSONAL + APP_SCHEME) ​

고객사 서버에서 앱스킴을 발급받아 클라이언트가 직접 토스 앱을 호출합니다.

Access Token 발급 ​

연동을 시작하기 전 Access Token이 필요합니다. 발급 방법은 시작하기 > Access Token 발급을 참고하세요.

본인확인 요청 ​

POST https://cert.toss.im/api/v2/sign/user/auth/id/request

본인확인을 시작하고 거래 ID(txId)를 발급합니다. 세 가지 방식을 지원합니다.

요청 ​

요청 헤더

이름필수설명
AuthorizationYBearer {access_token}
Content-TypeYapplication/json

요청 파라미터

파라미터필수설명
requestUrlY인증 완료 후 돌아올 고객사 URL. 표준창에서는 인증 후 리다이렉트 목적지로, 앱 방식에서는 콜백 기본 URL로 사용됩니다
requestTypeNUSER_NONE(표준창) 또는 USER_PERSONAL(개인정보 기반). 기본값: USER_NONE
triggerTypeUSER_PERSONAL 시 필수PUSH(앱 푸시) 또는 APP_SCHEME(앱스킴)
userNameUSER_PERSONAL 시 필수암호화된 이름
userPhoneUSER_PERSONAL 시 필수암호화된 전화번호 (숫자만)
userBirthdayUSER_PERSONAL 시 필수암호화된 생년월일 (YYYYMMDD)
sessionKeyUSER_PERSONAL 시 필수세션 암호화 키
successCallbackUrlNAPP_SCHEME 방식일 때 인증 성공 콜백 주소
failCallbackUrlNAPP_SCHEME 방식일 때 인증 실패 콜백 주소
nonceN중복 요청 방지용 파라미터
expireSecondsN인증 유효시간 (최대 1800초)

응답 파라미터

파라미터방식설명
txId공통거래 ID (반드시 저장·관리)
authUrlUSER_NONE표준창 URL (SDK와 함께 사용, 직접 호출 금지)
appSchemeAPP_SCHEME앱스킴 방식 전용 범용 앱 URI
androidAppUriAPP_SCHEMEPlay Store 폴백이 포함된 Chrome Intent 형식
iosAppUriAPP_SCHEMEApp Store 폴백이 포함된 Universal Link 형식
requestedDt공통최초 요청 시각 (ISO 8601)

표준창 방식 (USER_NONE) ​

고객이 토스 웹 인터페이스에서 직접 개인정보를 입력합니다.

요청

json
{
  "requestType": "USER_NONE",
  "requestUrl": "https://your-domain.com"
}

응답

json
{
  "resultType": "SUCCESS",
  "success": {
    "txId": "거래ID",
    "authUrl": "https://auth.cert.toss.im/start?serviceType=...",
    "requestedDt": "2022-02-13T17:52:22+09:00"
  }
}

앱 푸시 방식 (USER_PERSONAL + PUSH) ​

토스가 직접 고객 앱에 푸시를 전송합니다.

요청

json
{
  "requestType": "USER_PERSONAL",
  "triggerType": "PUSH",
  "requestUrl": "https://your-domain.com",
  "userName": "암호화된 이름",
  "userPhone": "암호화된 전화번호",
  "userBirthday": "암호화된 생년월일",
  "sessionKey": "세션키"
}

응답

json
{
  "resultType": "SUCCESS",
  "success": {
    "txId": "거래ID",
    "requestedDt": "2022-02-13T17:52:22+09:00"
  }
}

앱스킴 방식 (USER_PERSONAL + APP_SCHEME) ​

서버에서 앱스킴을 생성해 클라이언트가 직접 호출합니다.

요청

json
{
  "requestType": "USER_PERSONAL",
  "triggerType": "APP_SCHEME",
  "requestUrl": "https://your-domain.com",
  "userName": "암호화된 이름",
  "userPhone": "암호화된 전화번호",
  "userBirthday": "암호화된 생년월일",
  "sessionKey": "세션키",
  "successCallbackUrl": "your-scheme://success",
  "failCallbackUrl": "your-scheme://fail"
}

응답

json
{
  "resultType": "SUCCESS",
  "success": {
    "txId": "거래ID",
    "appScheme": "supertoss://toss-cert/...",
    "androidAppUri": "intent://...",
    "iosAppUri": "https://ul.toss.im?scheme=...",
    "requestedDt": "2022-02-13T17:52:22+09:00"
  }
}

원터치 인증 (앱 전용) ​

GET https://cert.toss.im/api-client/v1/transactions/{txId}

모바일 앱에서만 사용 가능하며, 개인정보 입력 없이 토스 앱을 직접 호출합니다. 서버-서버 통신이 아닌 클라이언트에서 호출합니다.

사전 조건

  • 본인확인 요청 API를 requestType: USER_NONE으로 먼저 호출
  • successCallbackUrl과 failCallbackUrl 포함

Path 파라미터

파라미터필수설명
txIdY본인확인 요청 API에서 발급받은 거래 ID

요청 예시

bash
curl --request GET 'https://cert.toss.im/api-client/v1/transactions/{txId}' \
  --header 'Authorization: Bearer {access_token}'

응답

json
{
  "resultType": "SUCCESS",
  "success": {
    "txId": "거래ID",
    "status": "REQUESTED",
    "appUri": {
      "android": "intent://...",
      "ios": "https://ul.toss.im?scheme=..."
    }
  }
}

본인확인 상태조회 ​

POST https://cert.toss.im/api/v2/sign/user/auth/id/status

사용자의 현재 인증 진행 상태를 확인합니다.

요청 ​

요청 파라미터

파라미터필수설명
txIdY상태 확인할 거래 ID

요청 예시

json
{
  "txId": "거래ID"
}

응답 ​

json
{
  "resultType": "SUCCESS",
  "success": {
    "txId": "거래ID",
    "status": "COMPLETED",
    "requestedDt": "2022-02-13T17:52:22+09:00"
  }
}
상태값설명
REQUESTED인증 요청됨
IN_PROGRESS인증 진행 중
COMPLETED인증 완료
EXPIRED유효시간 만료

WARNING

상태조회 결과로 완료를 판별하지 마세요. 반드시 결과조회 API를 기준으로 하세요.

본인확인 결과조회 ​

POST https://cert.toss.im/api/v2/sign/user/auth/id/result

사용자 인증 최종 결과와 개인정보를 조회합니다.

WARNING

  • 성공 기준 최대 2회 조회 가능
  • 인증 완료 후 60분 이내 조회 필수

요청 ​

요청 헤더

이름필수설명
AuthorizationYBearer {access_token}
Content-TypeYapplication/json

요청 파라미터

파라미터필수설명
txIdY결과 조회할 거래 ID
sessionKeyY응답 암호화용 세션 키 (매번 새로 생성)

요청 예시

json
{
  "txId": "거래ID",
  "sessionKey": "세션키"
}

성공 응답 ​

json
{
  "resultType": "SUCCESS",
  "success": {
    "txId": "거래ID",
    "status": "COMPLETED",
    "signature": "Base64인코딩된 전자서명 (DER 형식)",
    "completedDt": "2022-02-13T18:01:53+09:00",
    "requestedDt": "2022-02-13T17:52:22+09:00",
    "personalData": {
      "ci": "암호화된 CI",
      "name": "암호화된 이름",
      "birthday": "암호화된 생년월일",
      "gender": "MALE 또는 FEMALE",
      "nationality": "LOCAL 또는 FOREIGNER",
      "di": "암호화된 DI",
      "ageGroup": "ADULT 또는 MINOR"
    }
  }
}

personalData 필드

필드설명
ci연계정보
name이름
birthday생년월일 (8자리)
gender성별 (MALE / FEMALE)
nationality국적 (LOCAL / FOREIGNER)
di중복가입확인정보
ageGroup성인 여부 (ADULT / MINOR)

토스 표준창 UI 연동 ​

USER_NONE 방식 사용 시 토스 표준창 SDK가 필요합니다. 웹/앱 환경별 연동 방법은 토스 표준창 UI 연동을 참고하세요.

주의사항

  • 개인정보(userName, userPhone, userBirthday)는 반드시 암호화된 값으로 전달하세요. 암호화 알고리즘 및 세션 키 생성 절차는 공통 정보 > 개인정보 암복호화를 참고하세요.
  • sessionKey는 매 요청 시 새로 생성해야 합니다.
  • txId는 고유 거래 식별값으로 반드시 저장·관리하세요.
  • 결과조회는 성공 기준 최대 2회, 인증 완료 후 60분 이내에 호출하세요.