토스 인증

Appearance

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

간편인증 ​

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

이미 CI를 보유한 고객을 빠르게 확인합니다. 로그인, 가입 조회 등 개인정보 입력 없이 고객을 간단히 확인하고 싶을 때 활용하세요.

본인확인과의 차이

  • 본인확인: 처음 방문한 고객의 CI/DI를 새로 발급받습니다.
  • 간편인증: 이미 CI를 알고 있는 고객을 재확인합니다.

사전 준비 ​

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

연동 흐름 ​

표준창 방식 (USER_NONE) ​

앱 푸시 방식 (USER_PERSONAL + PUSH) ​

Access Token 발급 ​

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

간편인증 요청 ​

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

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

요청 ​

요청 헤더

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

요청 파라미터

파라미터필수설명
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"
}

응답

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",
  "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",
  "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/status

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

요청 ​

요청 헤더

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

요청 파라미터

파라미터필수설명
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/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",
    "completedDt": "2022-02-13T18:01:53+09:00",
    "personalData": {
      "ci": "암호화된 CI",
      "name": "암호화된 이름",
      "phone": "암호화된 전화번호",
      "birthday": "암호화된 생년월일",
      "gender": "MALE 또는 FEMALE",
      "nationality": "LOCAL 또는 FOREIGNER",
      "address": "암호화된 주소",
      "email": "암호화된 이메일"
    }
  }
}

personalData 필드

필드설명
ci연계정보
name이름
phone전화번호
birthday생년월일 (8자리)
gender성별 (MALE / FEMALE)
nationality국적 (LOCAL / FOREIGNER)
address주소
email이메일

토스 표준창 UI 연동 ​

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

주의사항

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