토스 인증

Appearance

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

전자서명 (다건) ​

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

여러 문서에 한 번에 서명합니다. 약관 묶음처럼 고객이 여러 문서를 한 번에 동의해야 하는 서비스에 활용하세요.

단건 vs 다건

  • 단건 전자서명: 문서 1개에 서명합니다.
  • 다건 전자서명: 여러 문서(예: 서비스 이용약관 + 개인정보 수집 동의)에 한 번에 서명합니다.

사전 준비 ​

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

연동 흐름 ​

Access Token 발급 ​

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

다건 전자서명 요청 ​

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

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

요청 ​

요청 헤더

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

요청 파라미터

파라미터필수설명
requestTypeYUSER_PERSONAL(개인정보 기반) 또는 USER_CI(CI 기반)
triggerTypeYPUSH(앱 푸시) 또는 APP_SCHEME(앱스킴)
userNameUSER_PERSONAL 시 필수암호화된 이름
userPhoneUSER_PERSONAL 시 필수암호화된 전화번호
userBirthdayUSER_PERSONAL 시 필수암호화된 생년월일 (YYYYMMDD)
sessionKeyUSER_PERSONAL 시 필수사용자 정보 암복호화 세션 키 (매번 새로 생성)
userCiUSER_CI 시 필수암호화된 CI
docsY서명할 문서 목록 (배열)
docs[].docTitleY문서 제목
docs[].docY원문 내용 (최대 2,000자 권장)
docs[].docTypeYTEXT, HTML, PDF 중 하나
docs[].docEncryptedN원문 암호화 여부 (기본값: false)
signatureTypeNPKCS7 (기본값) 또는 PKCS7_NO_CONTENT_WITH_ATTR
expireSecondsN인증 유효시간 (최대 1800초)
successCallbackUrlAPP_SCHEME 시 필수인증 성공 콜백 주소
failCallbackUrlAPP_SCHEME 시 필수인증 실패 콜백 주소

응답 파라미터

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

앱 푸시 방식 (PUSH) ​

요청

json
{
  "requestType": "USER_PERSONAL",
  "triggerType": "PUSH",
  "userName": "암호화된 이름",
  "userPhone": "암호화된 전화번호",
  "userBirthday": "암호화된 생년월일",
  "sessionKey": "세션키",
  "docs": [
    {
      "docTitle": "서비스 이용약관 동의",
      "doc": "본 약관에 동의합니다...",
      "docType": "TEXT"
    },
    {
      "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": "세션키",
  "docs": [
    {
      "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/docs/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/docs/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",
    "docs": [
      {
        "doc": "원본 서명 문서",
        "signedDoc": "Base64 인코딩된 서명 정보 (DER 형식)"
      }
    ],
    "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분 이내에 호출하세요.