공통 정보

토스인증 API 연동에 필요한 공통 기술 스펙입니다. 도메인, 프로토콜, 방화벽 설정, 개인정보 암복호화, 응답 형식을 다룹니다.

---

도메인

서비스별로 사용하는 도메인이 다릅니다.

용도	도메인
Access Token 발급	https://oauth2.cert.toss.im
본인확인·간편인증·전자서명 API	https://cert.toss.im
마이데이터 통합인증 API	https://mydata.cert.toss.im

---

프로토콜

모든 API는 HTTPS를 사용하며 TLS 1.2 이상만 지원합니다. 이전 버전의 SSL/TLS는 보안 취약점으로 인해 지원하지 않습니다.

---

방화벽 설정

아웃바운드 포트 443을 아래 IP로 허용하세요.

서비스	허용 IP
본인확인·간편인증·전자서명	117.52.3.222 117.52.3.235 211.115.96.222 211.115.96.235
마이데이터 통합인증	117.52.3.221 211.115.96.221

---

개인정보 암복호화

고객사와 토스 서버 간에 고객 개인정보를 주고받을 때는 데이터를 암호화합니다.

암호화 대상

상황	암호화 대상
인증 요청 시 (USER_PERSONAL)	이름, 생년월일, 휴대폰번호
전자서명 원문에 개인정보 포함 시	원문 전체
인증 결과 조회 시	CI, DI 등 개인정보

연동 방식(requestType)에 따른 암호화 필요 여부

토스인증 API는 인증 요청 시 requestType 파라미터로 연동 방식을 구분합니다.

• USER_NONE (표준창 방식): 고객이 토스 표준창에서 직접 개인정보를 입력합니다. 고객사 서버에서 토스 서버로 고객 정보를 전달하지 않으므로 요청 시 암호화가 불필요합니다. 단, 결과조회 시에는 반드시 sessionKey를 포함해야 합니다. (세션 키 사용 절차 참고)
• USER_PERSONAL (개인정보 기반 방식): 고객사가 개인정보를 암호화해서 전달합니다. 이름, 생년월일, 휴대폰번호를 암호화해야 합니다.

암호화 알고리즘

용도	알고리즘
세션 키 암호화	RSA/ECB/OAEPWithSHA-1AndMGF1Padding
개인정보 암호화	AES-256-GCM

세션 키 사용 절차

세션 키는 개인정보를 암복호화할 때 사용하는 1회용 키입니다. 매 API 호출 시 새로 생성해야 합니다.

TossCertSessionGenerator, encrypt(), getSessionKey(), decrypt()는 아래 Java SDK에서 제공하는 클래스와 메서드입니다.

인증 요청 시

1. TossCertSessionGenerator를 1회 초기화합니다.
2. 개인정보 포함 API 호출 전, 새로운 세션을 생성합니다.
3. encrypt()로 개인정보(이름, 생년월일, 전화번호)를 암호화합니다.
4. getSessionKey()로 세션 키를 가져와 요청 본문의 sessionKey 필드에 포함합니다.

결과 조회 시

1. 인증 완료 후 결과조회 전, 새로운 세션을 다시 생성합니다.
2. 새로운 sessionKey를 포함해 결과조회 API를 호출합니다.
3. decrypt()로 응답의 암호화된 개인정보를 복호화합니다. (무결성 검증 자동 포함)

SDK 및 코드 예시

개인정보 암복호화를 위한 Java SDK와 다국어 코드 샘플을 제공합니다.

리소스	링크
Java SDK	github.com/toss/toss-cert-java-sdk
다국어 코드 샘플	github.com/toss/toss-cert-examples

---

전자서명 형식

전자서명은 PKCS#7 형식 공개키 암호화 표준을 사용합니다. 전자서명 결과조회 API의 signedDoc 필드 및 본인확인·간편인증의 signature 필드가 이 형식으로 반환됩니다. 서명값에서 인증서를 추출하거나 유효성을 검증하는 방법은 인증서 유효성 확인을 참고하세요.

---

공통 응답 형식

모든 API 응답은 resultType 필드로 성공·실패를 구분합니다.

성공

{
  "resultType": "SUCCESS",
  "success": { ... }
}

실패

{
  "resultType": "FAIL",
  "error": {
    "errorType": 40101,
    "errorCode": "CE-AUTH-001",
    "reason": "유효하지 않은 접근토큰입니다",
    "title": null,
    "data": {}
  }
}

필드	설명
errorType	숫자 형식의 에러 코드
errorCode	CE- 시리즈 문자열 에러 코드
reason	사람이 읽을 수 있는 에러 메시지
title	에러 제목 (없는 경우 null)
data	추가 에러 데이터