계좌개설, 출금이체 동의 등 각종 계약・동의 원문이 포함된 전자문서를 확인하고 서명할 수 있습니다.
서버 인증을 위한 Access Token을 발급받는 API 입니다. 인증 방식 살펴보기
이미 유효한 토큰을 가지고 있는 상태에서 새로운 토큰 발급 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
}
전자서명을 시작하기 위한 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$cc575847-f549-4c1e-89c7-eff11743e05e$5AfwdVLSmDoxBERDIV8gDny2QLcOzYOqvgt1l4gqEA==",
"userPhone" : "v1$cc575847-f549-4c1e-89c7-eff11743e05e$OKtwqMR/RI+N3vx0FNtcx8GAoejDq5lb3wIr",
"userBirthday" : "v1$cc575847-f549-4c1e-89c7-eff11743e05e$OaNxoMR2RYaPiH7km5yJyZQ472+uWNEy",
"sessionKey" : "v1$cc575847-f549-4c1e-89c7-eff11743e05e$XTTyBJntTja9NfUaTaO09bQCtEApnn3dd7lN8s+jPA6qn5q5kBbSJEptazpSMqGFyB7P0XhnJSkRwukAuunesbm+e0p5tdQ7wiOkauM44FvZj/IwETTA74iLZTNrwmE3aYXv8b1wbIfQx/oT8k9+XNEPkHA0foCFtjF8MRnyjwpzR4hoi2sFk33xhoJa46kLGxz7d3z6r/KYKMFbwkQFOm81Nk8W+oJkT0AjdlOD075QrJ4zm9VReVvE4fT4Q1jY/5VzROt4GkqVvrziYbWRp9/v1/ETVyi5Lf+MceWHLS1MGicqUXfrfnFdqvOcZZytUkvb0AAyg75Sr5tgja55ma3t5AEu65IrO1Cop4wS/XhIwKpWUrMav5JI5X1iZ1tRznE7VRT/dsRLjgIX/wtZajY2ATG+feld2mmxD/mP/ET3JXsYKfmN3DkO10fQZY9915eUyDYm7NMS/U3l+VP8wMzd5WpWVjfxUvYP5eRwPM83hG9wFhHXV4ykodiX0BLRoERXou416uKDJR61b8xFFX+iDPnOfaeROlFFWj6zbK4tPfjRzyaWVQMmSM8igq7iBglehFo+EyyQnAAcUeda+P/7fQmwFDE1a8bQuXFBCwxNOOyPiJLV2+29pzKELcHa+WCrvcbHkOgG4EwjHHWmd17vUVXZGXOERsRuLQMM3mM=",
"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$f7bb9c0f-3a11-4b2c-a2ac-34e4893421af$03ojKCaV3OCmAiJiqeMSY5egQVPGkhQan98fhBFfP4xTCAM6/7trMA7ylGDcLW2MIFjP3Bx3SB0Gs9zSHdpZQpwWibpIrips5ddp+ilmkq4FTUyllHxtM6di4lj/o/ff5GHd/JDMXqs=",
"sessionKey" : "v1$f7bb9c0f-3a11-4b2c-a2ac-34e4893421af$fGh/E7bXA1dEbcNTeRCOekTSVCIQzd4QyYk/YZ0GllavG9YQzPeeh0JCn1m3HpaL9ABPz2vhtPPW29MF5mYKF8MR5AwhpkPmqoUqYvIcaP5nvHiLj0dUP3Vm0VJzVhzevqJPkwS3HFyzNHeWAFRcc2t9+AFhw3OFWXDWtlxKqk8oyqikPNXBXeqwQSJHpE0QJjC3wL5ahmyvIOxs4bD8TtQ5iV7msllnDsCE1mS4F/upYxQUDFoMTHBj2iEsJgAkz4Aa2r20PqjwG7xJfEqKjctdRx6QtJubO2q1lToVetQRtBdigrFXzLHldMJKLpk2pjOQDp09fyEiEVr58wkT2eK0DLetHBixsPqH0P2U+0XSz97xr1jD5CgnZo/2Z7i82JWxrlHO9SdxJLb6EvqtziwVEOy+BAoZ4uIg7FMJECkRbmvjUqSlftLQToj32t188XUaojQWoMTAlaxhiVlx4rSzGvDAenpv2GVWGl4ZSpDnBJjXq4T2UfooQjMCvuCnH2gJAktJeCEmORoiIZm5qqBxyd/0MYOcO+YsaUXXym8sbSEzA9z+a4lp/WfQPd43a46jZDTt7sgXkK0YuAJAsI1S1T/nA12gDgdcuriITjMisqEqigjWjkWHszTImaHSzGLjN3pedX/j5exzYmF21eRpnnowrHgEqN0P4xCJB64=",
"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"
}
}
응답 파라미터
- 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 실행하는 코드
토스앱이 설치되어 있으면 앱스킴을 실행하고 설치 되어있지 않다면 플레이 스토어로 이동해서 토스앱 설치를 유도하는 코드입니다.
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 실행하는 코드
토스앱이 설치되어 있으면 앱스킴을 실행하고 설치 되어있지 않다면 앱 스토어로 이동해서 토스앱 설치를 유도하는 코드입니다.
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.")
}
사용자의 전자서명 상태를 확인하기 위한 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"
}
}
실패응답
{
"resultType": "FAIL",
"error": {
"errorType": 0,
"errorCode": "CE3100",
"reason": "존재하지 않는 요청입니다",
"data": {},
"title": null
},
"success": null
}
응답 파라미터
- 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
를 사용합니다.
사용자의 서명 결과를 확인하기 위한 API로서 txId
로 결과를 조회할 수 있습니다.
전자서명 결과 조회 시, 반드시 서버 간 통신하시는 것을 권고드리며, 전자서명을 진행하실 때, 본인확인 결과로 수집한 정보와 비교, 검증하는 것을 권고 드립니다.
사용자 인증을 끝마친 후 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
}
}
}
실패응답
{
"resultType": "FAIL",
"error": {
"errorType": 0,
"errorCode": "CE3101",
"reason": "최종 결과는 2회만 조회할 수 있습니다.",
"data": {},
"title": null
},
"success": null
}
응답 파라미터
- 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
고정 - ageGroup String
암호화된 사용자의 성인여부 정보로
ADULT
또는MINOR