일반 전자서명

계좌개설, 출금이체 동의 등 각종 계약・동의 원문이 포함된 전자문서를 확인하고 서명할 수 있습니다.

토스인증 흐름

1. Access Token 발급 API

서버 인증을 위한 Access Token을 발급받는 API 입니다. 인증 방식 살펴보기

발급받은 Access Token은 모든 서비스 API 호출 시, 인증 용도로 사용됩니다. Access Token은 만료시간을 가지며, 토큰이 만료되면 유효한 토큰을 다시 발급받아 사용해야 합니다.

이미 유효한 토큰을 가지고 있는 상태에서 새로운 토큰 발급 API 를 반복 호출하지 마세요.

EndPoint

POST /token

요청

curl --request POST 'https://oauth2.cert.toss.im/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=test_a8e23336d673ca70922b485fe806eb2d' \
--data-urlencode 'client_secret=test_418087247d66da09fda1964dc4734e453c7cf66a7a9e3' \
--data-urlencode 'scope=ca'

요청 헤더

  • Content-Type 필수 · String

    application/x-www-form-urlencoded

요청 파라미터

  • grant_type 필수

    client_credentials

  • scope 필수

    ca

  • client_id 필수

    고객사에 발급된 클라이언트 아이디

  • client_secret 필수

    고객사에 발급된 클라이언트 시크릿

응답

{
"access_token": "eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY0OTIyMjk3OCwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MDc1ODk3OCwiaWF0IjoxNjQ5MjIyOTc4LCJqdGkiOiI4MDNjNDBjOC1iMzUxLTRmOGItYTIxNC1iNjc5MmNjMzBhYTcifQ.cjDZ0lAXbuf-KAgi3FlG1YGxvgvT3xrOYKDTstfbUz6CoNQgvd9TqI6RmsGZuona9jIP6H12Z1Xb07RIfAVoTK-J9iC5_Yp8ZDdcalsMNj51pPP8wso86rn-mKsrx1J5Rdi3GU58iKt0zGr4KzqSxUJkul9G4rY03KInwvl692HU19kYA9y8uTI4bBX--UPfQ02G0QH9HGTPHs7lZsISDtyD8sB2ikz5p7roua7U467xWy4BnRleCEWO2uUaNNGnwd7SvbjhmsRZqohs9KzDUsFjVhSiRNdHL53XJQ5zFHwDF92inRZFLu6Dw8xttPtNHwAD1kT84uXJcVMfEHtwkQ",
"scope": "ca",
"token_type": "Bearer",
"expires_in": 31536000
}
JSON

2. 일반 전자서명 요청 API

전자서명을 시작하기 위한 API로서 토스 인증 서버에서 txId를 발급합니다.

EndPoint

POST /api/v2/sign/doc/request

Case1. 앱 푸쉬를 이용해서 서명 요청하기

curl --location --request POST 'https://cert.toss.im/api/v2/sign/doc/request' \
--header 'Authorization: Bearer eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY0OTIyMjk3OCwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MDc1ODk3OCwiaWF0IjoxNjQ5MjIyOTc4LCJqdGkiOiI4MDNjNDBjOC1iMzUxLTRmOGItYTIxNC1iNjc5MmNjMzBhYTcifQ.cjDZ0lAXbuf-KAgi3FlG1YGxvgvT3xrOYKDTstfbUz6CoNQgvd9TqI6RmsGZuona9jIP6H12Z1Xb07RIfAVoTK-J9iC5_Yp8ZDdcalsMNj51pPP8wso86rn-mKsrx1J5Rdi3GU58iKt0zGr4KzqSxUJkul9G4rY03KInwvl692HU19kYA9y8uTI4bBX--UPfQ02G0QH9HGTPHs7lZsISDtyD8sB2ikz5p7roua7U467xWy4BnRleCEWO2uUaNNGnwd7SvbjhmsRZqohs9KzDUsFjVhSiRNdHL53XJQ5zFHwDF92inRZFLu6Dw8xttPtNHwAD1kT84uXJcVMfEHtwkQ' \
--header 'Content-Type: application/json' \
# 세션 키는 매 요청 시 새로 생성해야 합니다.
--data-raw '{
          "requestType" : "USER_PERSONAL",
          "triggerType" : "PUSH",
          "userName" : "v1$e6bddc20-6858-4a8d-b06c-7a3f8461c7a3$aMC2MHpP/6SoHGqBj1uJVOeyhgI1Dkvu5g==",
          "userPhone" : "v1$e6bddc20-6858-4a8d-b06c-7a3f8461c7a3$skgG78TkJiUU2M2UX67/1X5TgbupaWaNuwqp",
          "userBirthday" : "v1$e6bddc20-6858-4a8d-b06c-7a3f8461c7a3$s0AP78LmJClNV/o9HOFO7K0nj+5p7uT1",
          "sessionKey" : "v1$e6bddc20-6858-4a8d-b06c-7a3f8461c7a3$HI6ndcW/hT0wAycPfCKGFbo+MXH7HVs0bxUCRa2JyECuqKwJkJ5x5swD2Imartk1ybSWLjzSgdS2PTeIAyoQXfnEuTMR1d9rIcYtIgVhdMypC7clxC+uZKPZceRqcerWQMCobyBFZJEa8PvTm0FxvfOC8znXp9oxiV4UmLbPlFU6l7O8YO38lKfUU46QMvTBR9GVsRdvUvPOhSuz5r4TbBTaU+8GrkVbo8ebB6u8/oypOZvQgYCltatUXAeePortSptyKwYEA68YE2FUiu68U5Ufl+E4X/1ScWMgbfSVguiMxuBYX844swRkeWKRjMn6fYMygVEzuOr03y9iHZe644cPmDr+1WSd4lB+XYgbqsIIDBkFRf1OOLD0C9PGLWSe0F30rAY6vWcf9IGoybuJjPzjYZ8yYE5MaSsv+BM80ETSUQCAy1w/a5tOAfrf1PwgVptskrf7gUgpk/xbPF74wxI4Q8UC/cs33VOhYFKxQ/yewn6+gHHjuJykO5m/3tSuOtQCNXq6dW5ijhP6bPV/QBjIeIyiYO+F6kcBTIh1SxBlJo72zXU0PSpDv0huGcI6OaqIh/Zv5WXIXX83NQJc8Unlw/8YkLGkj+LqB/0VVn07zxgYg1k6QGMbdSSxqC/pRlpodpwhaDVIxC1sHI5q4pLuRVr5VA36cmHWWzKYsQI=",
          "serviceName" : "토스 출금이체",
          "docTitle" : "출금이체 동의문",
          "doc" : "토스 간편송금 등의 서비스를 원활하게 이용하기 위하여 앞서 입력한 계좌에 대한 출금이체 동의가 필요합니다. 동의를 누르면 입력한 계좌에서 오픈뱅킹을 통해 출금이체가 진행됩니다.",
          "docType" : "TEXT",
          "docEncrypted" : false,
          "signatureType" : "PKCS7"
    }'

Case 2. 토스 서버에서 생성하는 앱스킴을 이용해서 서명 요청하기

curl --location --request POST 'https://cert.toss.im/api/v2/sign/doc/request' \
--header 'Authorization: Bearer eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY0OTIyMjk3OCwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MDc1ODk3OCwiaWF0IjoxNjQ5MjIyOTc4LCJqdGkiOiI4MDNjNDBjOC1iMzUxLTRmOGItYTIxNC1iNjc5MmNjMzBhYTcifQ.cjDZ0lAXbuf-KAgi3FlG1YGxvgvT3xrOYKDTstfbUz6CoNQgvd9TqI6RmsGZuona9jIP6H12Z1Xb07RIfAVoTK-J9iC5_Yp8ZDdcalsMNj51pPP8wso86rn-mKsrx1J5Rdi3GU58iKt0zGr4KzqSxUJkul9G4rY03KInwvl692HU19kYA9y8uTI4bBX--UPfQ02G0QH9HGTPHs7lZsISDtyD8sB2ikz5p7roua7U467xWy4BnRleCEWO2uUaNNGnwd7SvbjhmsRZqohs9KzDUsFjVhSiRNdHL53XJQ5zFHwDF92inRZFLu6Dw8xttPtNHwAD1kT84uXJcVMfEHtwkQ' \
--header 'Content-Type: application/json' \
# 세션 키는 매 요청 시 새로 생성해야 합니다.
--data-raw '{
          "requestType" : "USER_CI",
          "triggerType" : "APP_SCHEME",
          "userCi" : "v1$be2b3fdc-d3c8-447e-bcae-7f42a090ef1b$5T1USAI+SrZbFbm5WTrEseOzQkibAwWPa3jPrD04OfIpjAQL3dpJLxjqBLDUAgLt8yLj5NsSX83oJGyuBap5YKQR9fPFWUo3Jly657KJyk+s3Y1mD7t2AT6U6bNYkZu29yZtHS6ksXU=",
          "sessionKey" : "v1$be2b3fdc-d3c8-447e-bcae-7f42a090ef1b$jB2/c37j8o2JWRpQTctOABc0vk+p/jB3mdgT3YdvlYnEXKDrssfogZh2NyH6Jk+bctO4vd7TKL7z0RrT/8iNSgRk+/tY3ElPzEU1kjtONCx8E23RqK/S1Bc8R9ZITT33pQBRBpbH6rnxnZMH8Y0km34xpvMoPf4bfXn4ntsNigGilUUQ9bVTUhheRygMk4InrJLQZEP/FpfZ5TKdtnDPW4dV3+ZOozXF5CXB4UGNa1z52rJO78ko8TSo1ufCjQzuEf3hMjx4S72X/trKyCgDm45OcXvdsJ6oC+01z7SdPaSGYVOEODEGcjUcK2kOX+G98bDedKr7744eybYWTuN113opctN9bEmgHJIkNsmmeCXhDg5993ML9htaKWWwGaFJ0qArqTesoiAJ3pF+Fz60cRC4FDLs39B+mH7mhn/n0y4vc8G/e0tjZ+NI7AbKvck1Rg+F2ZvEV839QqTIRSSplFAN+dJ+Ly4+YNtkoebmCqag2aPkqnSQ+j4ZO2lsqfgYiuJ9LP4RAP0lNJBpePApm4lgK6pOsa0pRADT98EPsSeCECWabgZDZM4KsJDWy4G42k8J1klpUc6p4IEqujJLswjF38EkHDxMJ9/kSM5/4Ws85aY9Xj3fVpAZyAEpQeulC17MnAeBLdPy7GsnmRC9vDqZOfqlxCrP4YOUXaTaDjs=",
          "serviceName" : "토스 출금이체",
          "docTitle" : "출금이체 동의문",
          "doc" : "토스 간편송금 등의 서비스를 원활하게 이용하기 위하여 앞서 입력한 계좌에 대한 출금이체 동의가 필요합니다. 동의를 누르면 입력한 계좌에서 오픈뱅킹을 통해 출금이체가 진행됩니다.",
          "docType" : "TEXT",
          "docEncrypted" : false,
          "signatureType" : "PKCS7"
    }'

요청 파라미터

  • requestType String
    • USER_PERSONAL : 고객의 이름, 생년월일, 전화번호 정보를 기반으로 인증 요청 (암호화된 userName, userPhone, userBirthday 정보 필수)

    • USER_CI : 고객사에서 관리하는 고객의 CI 정보를 기반으로 인증 요청 (암호화된 userCi 정보 필수)

      USER_CI 값으로 요청되는 경우 서명 결과조회 API 응답에서 CI, DI를 수신할 수 없습니다.
  • triggerType 필수 · String
    • PUSH : 토스 앱 푸쉬를 이용해서 고객의 토스 앱으로 직접 푸쉬를 발송하고 인증을 진행하는 방식
    • APP_SCHEME : 토스 인증 서버에서 인증 결과로 전달하는 OS별 앱스킴을 고객사 서버에서 직접 호출하고 인증을 진행하는 방식
  • userName String

    requestType이 USER_PERSONAL인 경우에만 필수로 전달하는 고객의 이름

    평문이 아닌 반드시 암호화된 값으로 전달해야 합니다. 개인정보 암복호화 확인하기

  • userPhone String

    requestType이 USER_PERSONAL인 경우에만 필수로 전달하는 고객의 휴대폰번호로 문자 포함없이 순수한 숫자형태로 전달 필요

    평문이 아닌 반드시 암호화된 값으로 전달해야 합니다. 개인정보 암복호화 확인하기

  • userBirthday String

    requestType이 USER_PERSONAL인 경우에만 필수로 전달하는 고객의 생년월일 8자리 YYYYMMDD형식

    평문이 아닌 반드시 암호화된 값으로 전달해야 합니다. 개인정보 암복호화 확인하기

  • sessionKey String

    API에서 사용자의 개인정보 전달이 필요한 경우 즉, requestType이 USER_PERSONAL또는 USER_CI인 경우는 필수 파라미터

    인증 요청과 응답을 AES 암복호화 할 때 사용되는 세션 키로 매 요청 시 마다 새로 생성해서 암호화된 개인정보와 함께 전달해야 합니다. 세션키 생성 방법 확인하기

  • userCi String

    requestType이 USER_CI인 경우에만 필수로 전달하는 고객의 CI

    평문이 아닌 반드시 암호화된 값으로 전달해야 합니다. 개인정보 암복호화 확인하기

  • serviceName 필수 · String

    고객의 토스 앱 인증화면에 보이는 서비스 이름으로 계약서 제목 또는 동의문 제목을 포함하면 좋습니다.

    최대 50자 까지 가능합니다.

  • docTitle 필수 · String

    고객의 토스 앱 인증화면에 보이는 계약・동의 문서의 제목

  • doc 필수 · String

    고객의 토스 앱 인증화면에서 문서의 제목(docTitle)을 눌렀을 때 나오는 상세한 계약・동의 원문 내용

    최대 2,000자 이내의 내용을 권장합니다. 누군가를 특정할 수 있는 개인정보가 포함된 원문이라면 보안을 위해 원문 암호화가 필요합니다.

    개인정보 암복호화 확인하기
  • docType 필수 · String

    원문의 형태

    • TEXT : 원문 내용을 그대로 보여주는 텍스트 형태

    • HTML : 원문 내용을 HTML 형태로 보여주는 형태

    • PDF : PDF 서명을 위해 원문 내용을 보여주지 않고 hash값만 서명하는 형태

  • docEncrypted String

    원문 암호화 여부

    원문(doc)에 고객 개인정보를 포함한다면 true로 선언하고, doc에 포함된 원문은 모두 암호화된 값으로 전달해야 합니다. 그 외의 경우는 기본이 false입니다.

  • signatureType String

    전자서명 방식으로 기본은 PKCS7 으로 고정

    PDF 등 원문의 크기가 큰 전자서명을 사용하는 경우 PKCS7_NO_CONTENT_WITH_ATTR 으로 선언하고 해당 PDF 컨텐츠를 hash한 후에 원문(doc)을 반드시 base64 encode 요청값으로 전달해야 합니다.

  • expireSeconds Number

    인증을 할 수 있는 유효시간으로 최대 1800(초)으로 설정 가능

  • successCallbackUrl String

    triggerType이 APP_SCHEME인 경우에만 지원하는 기능으로, 토스 앱 인증이 성공적으로 완료되고 돌아갈 고객사 앱스킴 주소

  • failCallbackUrl String

    triggerType이 APP_SCHEME인 경우에만 지원하는 기능으로, 토스 앱 인증이 실패 했을 때 돌아갈 고객사 앱스킴 주소

성공응답

// Case1. 앱 푸쉬를 이용해서 서명 요청한 경우의 결과 데이터
// 결과가 조회되는 시점과 동시에 인증 요청으로 전달된 사용자의 토스 앱으로 푸시가 발송됩니다.
{
"resultType": "SUCCESS",
"success": {
"txId": "60940525-9a59-47db-b0eb-4f029b9faf1e",
"appScheme": null,
"androidAppUri": null,
"iosAppUri": null,
"requestedDt": "2022-03-13T17:52:22+09:00"
}
}
// Case 2. 토스 서버에서 생성하는 앱 스킴을 이용해서 서명 요청한 경우의 결과 데이터
// 생성된 앱스킴 그대로 호출해야 합니다.
{
"resultType": "SUCCESS",
"success": {
"txId": "e9af318d-2151-4b67-9818-def01983a623",
"appScheme": "supertoss://toss-cert/v2/sign/doc?txId=e9af318d-2151-4b67-9818-def01983a623&_minVerAos=5.36.0&_minVerIos=5.10.0",
"androidAppUri": "intent://toss-cert/v2/sign/doc?txId=e9af318d-2151-4b67-9818-def01983a623&_minVerAos=5.36.0&_minVerIos=5.10.0#Intent;scheme=supertoss;package=viva.republica.toss;end",
"iosAppUri": "https://ul.toss.im?scheme=supertoss%3A%2F%2Ftoss-cert%2Fv2%2Fsign%2Fdoc%3FtxId%3De9af318d-2151-4b67-9818-def01983a623%26_minVerAos%3D5.36.0%26_minVerIos%3D5.10.0",
"requestedDt": "2022-03-13T17:52:22+09:00"
}
}
JSON

응답 파라미터

  • resultType 필수 · String
    요청 결과 (성공: SUCCESS, 실패: FAIL)
  • errorCode String
    요청이 실패한 경우 반환되는 에러코드 (인증 에러코드 확인하기)
  • reason String
    에러코드에 해당하는 에러 메시지
  • txId String
    서명 요청 트랜잭션 아이디로 거래를 고유할 수 있는 값
    특정 거래를 고유할 수 있는 값이므로 반드시 저장 관리해야 합니다.
  • requestedDt String
    서명 요청 시간

    ISO 8601 형식인 YYYY-MM-DDThh:mm:ss±hh:mm 를 사용합니다.

  • appScheme String

    triggerType이 APP_SCHEME인 경우에만 전달되는 토스인증 앱 스킴

  • androidAppUri String

    triggerType이 APP_SCHEME인 경우에만 전달되는 안드로이드 인증 앱 스킴 값으로 appScheme과 같은 역할을 하지만, Chrome Intent를 사용하기 때문에 고객사의 추가 기능 구현없이 토스 앱 설치 유무를 판별할 수 있는 장점이 있습니다.
    클라이언트에서 호출하는 코드는 아래 가이드를 참고해주세요.

ㄴAndroid Chrome Intent 실행하는 코드

토스앱이 설치되어 있으면 앱스킴을 실행하고 설치 되어있지 않다면 플레이 스토어로 이동해서 토스앱 설치를 유도하는 코드입니다.

Kotlin
val intent = Intent.parseUri(androidAppUri, Intent.URI_INTENT_SCHEME)
try {
startActivity(intent)
} catch (e: ActivityNotFoundException) {
val marketIntent = Intent(Intent.ACTION_VIEW).apply {
data = Uri.parse("market://details?id=" + intent.`package`)
}
startActivity(marketIntent)
}
크롬 인텐트 문서 참고하기
  • iosAppUri String

    triggerType이 APP_SCHEME인 경우에만 전달되는 iOS 인증 앱 스킴 값으로 appScheme과 같은 역할을 하지만, Universal Link를 사용하기 때문에 안드로이드와 마찬가지로 고객사의 추가 기능 구현 없이 토스 앱 설치 유무를 판별할 수 있는 장점이 있습니다.
    클라이언트에서 호출하는 코드는 아래 가이드를 참고해주세요.

ㄴiOS Universal Link 실행하는 코드

토스앱이 설치되어 있으면 앱스킴을 실행하고 설치 되어있지 않다면 앱 스토어로 이동해서 토스앱 설치를 유도하는 코드입니다.

Swift
if let appURL = URL(string: "universal link string") {
UIApplication.shared.open(appURL) { success in
if success {
print("The URL was delivered successfully.")
} else {
print("The URL failed to open.")
}
}
} else {
print("Invalid URL specified.")
}
애플 공식 문서 참고하기

3. 일반 전자서명 상태조회 API

사용자의 전자서명 상태를 확인하기 위한 API로서 txId로 현재의 인증 진행 상태를 확인할 수 있습니다.

사용자의 인증 진행상태를 조회하는 용도로 사용할 수 있고, 상태조회 API의 결과 값으로 인증완료 상태를 처리하지 마세요. 토스에서는 결과조회 API를 기준으로 인증완료를 판별합니다.

EndPoint

POST /api/v2/sign/doc/status

요청

curl --location --request POST 'https://cert.toss.im/api/v2/sign/doc/status' \
--header 'Authorization: Bearer eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY0OTIyMjk3OCwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MDc1ODk3OCwiaWF0IjoxNjQ5MjIyOTc4LCJqdGkiOiI4MDNjNDBjOC1iMzUxLTRmOGItYTIxNC1iNjc5MmNjMzBhYTcifQ.cjDZ0lAXbuf-KAgi3FlG1YGxvgvT3xrOYKDTstfbUz6CoNQgvd9TqI6RmsGZuona9jIP6H12Z1Xb07RIfAVoTK-J9iC5_Yp8ZDdcalsMNj51pPP8wso86rn-mKsrx1J5Rdi3GU58iKt0zGr4KzqSxUJkul9G4rY03KInwvl692HU19kYA9y8uTI4bBX--UPfQ02G0QH9HGTPHs7lZsISDtyD8sB2ikz5p7roua7U467xWy4BnRleCEWO2uUaNNGnwd7SvbjhmsRZqohs9KzDUsFjVhSiRNdHL53XJQ5zFHwDF92inRZFLu6Dw8xttPtNHwAD1kT84uXJcVMfEHtwkQ' \
--header 'Content-Type: application/json' \
--data-raw '{
      "txId": "c3776b22-7c48-4b47-900e-5920253b7ece"
    }'

요청 파라미터

  • txId 필수 · String

    상태 확인이 필요한 인증 요청 트랜잭션 아이디

성공응답

{
"resultType": "SUCCESS",
"success": {
"txId": "c3776b22-7c48-4b47-900e-5920253b7ece",
"status": "REQUESTED",
"requestedDt": "2022-02-20T20:22:22+09:00"
}
}
JSON

실패응답

{
"resultType": "FAIL",
"error": {
"errorType": 0,
"errorCode": "CE3100",
"reason": "존재하지 않는 요청입니다",
"data": {},
"title": null
},
"success": null
}
JSON

응답 파라미터

  • resultType 필수 · String

    요청 결과 (성공: SUCCESS, 실패: FAIL)

  • errorCode String

    요청이 실패한 경우 반환되는 에러코드 (인증 에러코드 확인하기)

  • reason String

    에러코드에 해당하는 에러 메시지

  • txId String

    상태를 조회한 인증 요청 트랜잭션 아이디

  • status String
    인증 상태의 종류
    • REQUESTED : 토스 인증서버에서 사용자의 토스 앱으로 인증이 요청된 상태

    • IN_PROGRESS : 사용자가 인증을 진행 중인 상태

    • COMPLETED : 고객이 인증을 완료한 상태

    • EXPIRED : 유효시간 만료로 인증 진행이 불가한 상태

  • requestedDt String
    최초 서명 요청된 시간

    ISO 8601 형식인 YYYY-MM-DDThh:mm:ss±hh:mm 를 사용합니다.

4. 일반 전자서명 결과조회 API

사용자의 서명 결과를 확인하기 위한 API로서 txId로 결과를 조회할 수 있습니다.

결과조회 API는 성공 기준으로 최대 2회까지 조회가 가능합니다.
사용자 인증을 끝마친 후 60분(1시간) 이내 결과조회를 끝내야 합니다. 60분을 초과한 경우 결과조회가 제한되며 인증요청 API부터 다시 시작해야 합니다.

EndPoint

POST /api/v2/sign/doc/result

Case1. 앱 푸쉬 또는 앱 스킴으로 인증된 거래 결과 조회하기

curl --location --request POST 'https://cert.toss.im/api/v2/sign/doc/result' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJ0ZXN0X2E4ZTIzMzM2ZDY3M2NhNzA5MjJiNDg1ZmU4MDZlYjJkIiwiYXVkIjoidGVzdF9hOGUyMzMzNmQ2NzNjYTcwOTIyYjQ4NWZlODA2ZWIyZCIsIm5iZiI6MTY1MDYxMzU4OSwic2NvcGUiOlsiY2EiXSwiaXNzIjoiaHR0cHM6XC9cL2NlcnQudG9zcy5pbSIsImV4cCI6MTY4MjE0OTU4OSwiaWF0IjoxNjUwNjEzNTg5LCJqdGkiOiIzOWIyMWQ4MS1lYzE0LTQ4MTgtYTI1NS05OWJhYzE2NjIxYWMifQ.UkJCWfCNSWLVeKx0zGzpMn3WyUUQZ9n6Vyeo51s44bKXscC5W_QyYqqBrgnCetOud3xaugx8Ba-EnsfHxtcvIPKFHG2mGYMG04JBkQ0Vf53vf06RdglyUUt8rHDqZmcMWjFs7QTSrxKKUIVUmo0e6J2pjA9ARIPLFU7idHWTnZbtGYCx65jrii6tk9NBYhSOKOsAkdpF2_ZwKiLuuadY-fPEQ1c97eQr0zOVbpubLcmtbc-dq3LTUhKbhk-nelqlhZB_rxqtdkWgWjb_j8OKi67pM0KI3X5uEus0kijMMtpzJt9n1mH1BgXpOrA2Fm-9jOc0_BOm3C3hRng3RPFRBg' \
# 세션 키는 매 요청 시 새로 생성해야 합니다.
--data-raw '{
       "txId" : "60940525-9a59-47db-b0eb-4f029b9faf1e",
       "sessionKey" : "v1$daa566c5-3637-4dd9-b03d-b0958063a976$Fsn3U/ltwv1ilRVgbyQB7JsrhXrDf9/HsZ0Tw7gS0CxL3T0lIHTGXrCS8pOrlXRuNDeiyFo6omSL6iBWnMwKQ34FsWSfiMPKbE196P50Bengjofr0SSFJNrF2rW6PqdlE7FOqpJmy5ZCBdlnlTa6LPnVEbnSN2J7DRubg1K+2lb3tyxqIty+R0Y5Rh32xJ/LlX/RuQZYdmQTshHowg7aYti6SwsB5RLIZkzGucI22jFTIoRXYKCS1Uu2KmQWpNiIOheHyhs6vWmwRPgXjU2+lVs6pJIi5/BeE2rVu7xLA4Ss1iyp5JXaHz0HGFW0TI5BvnZEn6l/UZSc4MOiyls4x+4JwO4vOUh3Fbbcd31tYD23H1JbhR2/3Af1bULtIT/BmiLwBHpajcq+hY6n1TPT7GdZd0tt5PVuBBwsNKiTdk8hWKts9gdKm6BPQfkSUPYWKh9HEOMdWidrmtctXh5HZcs6AJconFPaQgcLjeu8f66yzdPOTzV81+LsUVtfVowd/lcErLz7d9KJhogFkn2m82w22J5Ks5oY6LqqpvYfIGGiEN2Nxo3SYMmURiBwYNmMrEk7vVc0UGWE4n778CZbHXhPpad9NduTkou45ncB+oUc3NgLPa33o7tBBGk/rGtNWELmDcMaaQYBQYm2sjHCQpG2KPaKj7Vty6PnEKgoRsY="
  }'

요청 파라미터

  • txId 필수 · String

    결과 확인이 필요한 서명 요청 트랜잭션 아이디

  • sessionKey String

    API에서 사용자의 개인정보 전달이 필요한 경우 즉, 앱 푸쉬 또는 앱 스킴 방식으로 인증을 진행한 경우 txId와 함께 sessionKey를 전달해야 합니다. 토스 서버에서 결과조회의 응답으로 암호화된 개인정보를 전달하기 때문입니다.

    인증 요청과 응답을 AES 암복호화 할 때 사용되는 세션 키로 매 요청 시 마다 새로 생성해서 암호화된 개인정보와 함께 전달해야 하고, 인증 요청에서 사용된 세션 키를 재 사용하지 마세요.

    세션키 생성 방법 확인하기

성공응답

// 결과조회 응답에서는 인증을 호출하는 방식에 상관없이 동일한 바디 파라미터를 제공합니다.
{
"resultType": "SUCCESS",
"success": {
"txId": "60940525-9a59-47db-b0eb-4f029b9faf1e",
"status": "COMPLETED",
"doc": "토스 간편송금 등의 서비스를 원활하게 이용하기 위하여 앞서 입력한 계좌에 대한 출금이체 동의가 필요합니다. 동의를 누르면 입력한 계좌에서 오픈뱅킹을 통해 출금이체가 진행됩니다.",
"signedDoc": "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",
"signatureType": "PKCS7",
"docEncrypted": false,
"randomValue": null,
"userCiToken": null,
"completedDt": "2022-03-13T18:01:53+09:00",
"requestedDt": "2022-03-13T18:00:26+09:00",
"personalData": {
"ci": "v1$b88f8717-8e76-4276-bed0-f769a8baf7be$X3g52aAyCBirz0UVp1oNRq0SfGtj66vGtUT3rp1aSdm1h//xmpm7vdf48fbGI2i7VTBj6TKG2rqanP6Yo9MiTQu63C8kLWayzWAMp+RLyXLovvnFb9SxxdblRtZbj5KRNlBWK9t2VXI=",
"name": "v1$b88f8717-8e76-4276-bed0-f769a8baf7be$9oiJBRei1KI/SgXtXGmkfNHu+pdAUHXBxA==",
"birthday": "v1$b88f8717-8e76-4276-bed0-f769a8baf7be$LQgw26ExChwWi8cQQz6GrdMAdMZGyaEI",
"gender": "v1$b88f8717-8e76-4276-bed0-f769a8baf7be$WnREqd1HM/Ci7p+3KIqROusVkYeSAQ==",
"nationality": "v1$b88f8717-8e76-4276-bed0-f769a8baf7be$UH5Kqd3dPV1daxw0i23eMWjeXcXC",
"ci2": null,
"di": "v1$2e161d9d-e620-443e-9a27-8db41cc96cf9$6GKr2zaUWWfI6rpJ6/AV9U4W0S4nhAMFIFLkt5CS6N8Gjb1Oc/dpitkMSSvLroDO5b6zdl9bufGSQ6SiVQdlYN2OWYFBr/Hb4e4AYwQpFxDbpi9ksYt52aFa3G2DwaNOQMUBkyQ1IWc=",
"ciUpdate": null
}
}
}
JSON

실패응답

{
"resultType": "FAIL",
"error": {
"errorType": 0,
"errorCode": "CE3101",
"reason": "최종 결과는 2회만 조회할 수 있습니다.",
"data": {},
"title": null
},
"success": null
}
JSON

응답 파라미터

  • resultType 필수 · String

    요청 결과 (성공: SUCCESS, 실패: FAIL)

  • errorCode String

    요청이 실패한 경우 반환되는 에러코드 (인증 에러코드 확인하기)

  • reason String

    에러코드에 해당하는 에러 메시지

  • txId String
    결과를 조회한 인증 요청 트랜잭션 아이디
  • status String

    COMPLETED

    결과 조회가 정상적으로 됐을 때 반환되는 상태

  • doc String

    전자서명 요청에서 전달한 계약・동의 등의 원문 내용으로 서명 요청에서 docEncrypted 값이 true인 경우에는 암호화된 원문이 결과로 전달되고 false인 경우에는 평문으로 전달됩니다.

  • signedDoc String

    사용자가 서명한 전자서명 정보

    Base64인코딩된 DER값으로 사용자 식별을 위해 txId와 함께 반드시 저장 관리 해야 합니다.

    인증서 유효성 확인하는 방법 알아보기
  • signatureType String
    전자서명 방식

    기본은 PKCS7으로 반환됩니다.

  • docEncrypted String
    원문 암호화 여부

    전자서명 요청에서 원문에 개인정보 포함 여부에 따라 정한 원문 암호화 여부

  • randomValue String

    현재 버전에서 미사용으로 null 고정

  • userCiToken String

    현재 버전에서 미사용으로 null 고정

  • completedDt String
    사용자가 서명을 끝마친 시간

    ISO 8601 형식인 YYYY-MM-DDThh:mm:ss±hh:mm 를 사용합니다.

  • requestedDt String
    최초 서명 요청된 시각

    ISO 8601 형식인 YYYY-MM-DDThh:mm:ss±hh:mm 를 사용합니다.

  • personalData Object
    인증을 진행한 사용자의 개인정보입니다.
    토스 테스트 환경에서는 아래 모든 개인정보를 제공하지만 실제 토스 앱으로 테스트한 사용자의 개인정보가 아닌 토스가 생성한 가상 인물의 개인정보를 암호화해서 전달합니다.

    라이브 환경에서는 사업자가 바로 신청하기에서 신청한 개인정보만 String 형태로 전달됩니다.

  • ci String

    암호화된 사용자의 ci

  • name String

    암호화된 사용자의 이름

  • birthday String

    암호화된 사용자의 생년월일 8자리

  • gender String

    암호화된 사용자의 성별정보로 MALE 또는 FEMALE

  • nationality String

    암호화된 사용자의 국적정보로 LOCAL 또는 FOREIGNER

  • ci2 String

    예측할 수 없는 상황에서 ci 유출 대응을 위한 임시 파리미터로 null 고정

  • di String

    암호화된 사용자의 di

  • ciUpdate String

    예측할 수 없는 상황에서 ci 유출 대응을 위한 임시 파리미터로 null 고정

  • 더 궁금한 내용이 있나요?