전자서명 (단건)

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

계좌개설, 이체 출금동의, 보험계약, 대출 약관 동의 등 고객의 서명이 필요한 전자문서에 법적 효력 있는 서명을 받을 수 있습니다.

단건 vs 다건

단건 전자서명: 문서 1개에 서명합니다.
다건 전자서명: 여러 문서(예: 약관 묶음)에 한 번에 서명합니다.

사전 준비

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

테스트 환경 자격증명 확인 — Client ID·Secret이 필요합니다.
방화벽 설정 — 서버에서 토스 API를 호출할 수 있도록 아웃바운드 IP를 허용하세요.
개인정보 암복호화 방식 확인 — USER_PERSONAL 방식 사용 시 필수입니다.

연동 흐름

앱 푸시 방식 (`PUSH`)

앱스킴 방식 (`APP_SCHEME`)

Access Token 발급

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

전자서명 요청

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

전자서명을 시작하고 거래 ID(txId)를 발급합니다.

요청

요청 헤더

이름	필수	설명
Authorization	Y	`Bearer {access_token}`
Content-Type	Y	`application/json`

요청 파라미터

파라미터	필수	설명
requestType	Y	`USER_PERSONAL`(개인정보 기반) 또는 `USER_CI`(CI 기반)
triggerType	Y	`PUSH`(앱 푸시) 또는 `APP_SCHEME`(앱스킴)
userName	`USER_PERSONAL` 시 필수	암호화된 이름
userPhone	`USER_PERSONAL` 시 필수	암호화된 전화번호
userBirthday	`USER_PERSONAL` 시 필수	암호화된 생년월일 (`YYYYMMDD`)
sessionKey	`USER_PERSONAL` 시 필수	사용자 정보 암복호화 세션 키 (매번 새로 생성)
userCi	`USER_CI` 시 필수	암호화된 CI
docTitle	Y	계약·동의 문서 제목
doc	Y	원문 내용 (최대 2,000자 권장)
docType	Y	`TEXT`, `HTML`, `PDF` 중 하나
docEncrypted	N	원문 암호화 여부 (기본값: `false`)
signatureType	N	`PKCS7` (기본값) 또는 `PKCS7_NO_CONTENT_WITH_ATTR`
expireSeconds	N	인증 유효시간 (최대 1800초)
successCallbackUrl	`APP_SCHEME` 시 필수	인증 성공 콜백 주소
failCallbackUrl	`APP_SCHEME` 시 필수	인증 실패 콜백 주소

응답 파라미터

파라미터	방식	설명
`txId`	공통	거래 ID (반드시 저장·관리)
`appScheme`	`APP_SCHEME`	앱스킴 방식 전용 범용 앱 URI
`androidAppUri`	`APP_SCHEME`	Play Store 폴백이 포함된 Chrome Intent 형식
`iosAppUri`	`APP_SCHEME`	App Store 폴백이 포함된 Universal Link 형식
`requestedDt`	공통	최초 요청 시각 (ISO 8601)

앱 푸시 방식 (`PUSH`)

요청

json

{
  "requestType": "USER_PERSONAL",
  "triggerType": "PUSH",
  "userName": "암호화된 이름",
  "userPhone": "암호화된 전화번호",
  "userBirthday": "암호화된 생년월일",
  "sessionKey": "세션키",
  "docTitle": "서비스 이용 약관 동의",
  "doc": "본 약관에 동의합니다...",
  "docType": "TEXT"
}

응답

json

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

앱스킴 방식 (`APP_SCHEME`)

요청

json

{
  "requestType": "USER_PERSONAL",
  "triggerType": "APP_SCHEME",
  "userName": "암호화된 이름",
  "userPhone": "암호화된 전화번호",
  "userBirthday": "암호화된 생년월일",
  "sessionKey": "세션키",
  "docTitle": "서비스 이용 약관 동의",
  "doc": "본 약관에 동의합니다...",
  "docType": "TEXT",
  "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"
  }
}

전자서명 상태조회

POST https://cert.toss.im/api/v2/sign/doc/status

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

요청

요청 헤더

이름	필수	설명
Authorization	Y	`Bearer {access_token}`
Content-Type	Y	`application/json`

요청 파라미터

파라미터	필수	설명
txId	Y	상태 확인할 거래 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/doc/result

최종 서명 결과를 조회합니다.

WARNING

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

요청

요청 헤더

이름	필수	설명
Authorization	Y	`Bearer {access_token}`
Content-Type	Y	`application/json`

요청 파라미터

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

요청 예시

json

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

성공 응답

json

{
  "resultType": "SUCCESS",
  "success": {
    "txId": "거래ID",
    "status": "COMPLETED",
    "doc": "원본 서명 문서",
    "signedDoc": "Base64 인코딩된 서명 정보 (DER 형식)",
    "completedDt": "2022-02-13T18:01:53+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`)

주의사항

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

전자서명 (단건) ​

사전 준비 ​

연동 흐름 ​

앱 푸시 방식 (PUSH) ​

앱스킴 방식 (APP_SCHEME) ​

Access Token 발급 ​

전자서명 요청 ​

요청 ​

앱 푸시 방식 (PUSH) ​

앱스킴 방식 (APP_SCHEME) ​

전자서명 상태조회 ​

요청 ​

응답 ​

전자서명 결과조회 ​

요청 ​

성공 응답 ​

전자서명 (단건)

사전 준비

연동 흐름

앱 푸시 방식 (`PUSH`)

앱스킴 방식 (`APP_SCHEME`)

Access Token 발급

전자서명 요청

요청

앱 푸시 방식 (`PUSH`)

앱스킴 방식 (`APP_SCHEME`)

전자서명 상태조회

요청

응답

전자서명 결과조회

요청

성공 응답