빌링키 처리결과 callback
사용자가 토스 앱을 통해 빌링 등록을 '성공적'으로 완료한 경우 토스 Server는 가맹점이 설정한 resultCallback URL을 통해 결과를 전달합니다. (실패한 경우는 전달하지 않습니다.)
- 토스 쪽에서 삭제가 발생되는 경우 토스 pay Server에서 삭제(
REMOVED) callback을 보낼 수 있음을 참고해야 합니다. - callback에 대한 응답의 HTTP status code가 200인 경우에만 '정상' 수신으로 간주하며, 그 외의 응답 코드는 미수신으로 실패한 것으로 인식하여 3분 간격으로 최대 4번 접근을 시도합니다.
- 빌링키 생성결과 callback의 Payload는 다음과 같습니다.
각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.
파라미터
요청 처리에 따른 빌링키 상태
-
ACTIVATED : 빌링키 활성화 완료
빌링키 생성요청에 따라, 토스 → 가맹점으로 '정상처리'를 알리는 콜백 -
REMOVED : 빌링키 삭제 완료
토스 → 가맹점으로 빌링키 삭제를 요청할 수 있다. 그 때, '삭제완료' 상태를 알리는 콜백
상태 처리시간
action 에 따라 각 상태의 처리시간을 전달합니다.
가맹점이 생성한 사용자 식별 값
가맹점의 요청 값 그대로를 전달합니다.
가맹점이 생성한 표시 가능한 빌링키 식별 값
가맹점의 요청 값 그대로를 전달합니다.
활성화/삭제 자동결제 사용자 빌링키
사용자가 토스에서 인증한 결제수단
선택한 결제수단에 따라 토스머니(TOSS_MONEY) 또는 카드(CARD)를 전달합니다.
승인된 카드의 타입을 구분
선택한 결제수단에 따라 신용카드(CREDIT), 체크카드(CHECK), 선불카드(PREPAYMENT)를 전달합니다.
카드 사용자 구분
- PERSONAL : 본인 카드
- PERSONAL_FAMILY : 가족 카드
- CORP_PERSONAL : 법인지정 결제계좌 임직원
- CORP_PRIVATE : 법인 공용
- CORP_COMPANY : 법인지정 결제계좌 회사(하나카드만)
사용자가 선택한 카드의 카드코드
사용자가 선택한 결제수단(payMethod)이 '카드'인 경우 토스가 정의한 카드코드를 전달합니다.
사용자가 선택한 카드의 카드사명
사용자가 선택한 결제수단(payMethod)이 '카드'인 경우 카드사명을 함께 전달합니다.
사용자가 선택한 카드의 번호
카드번호 16자리 중 중간자리는 마스킹됩니다.
사용자가 선택한 카드의 끝 4자리
사용자가 선택한 결제수단(payMethod)이 '카드'인 경우 카드번호를 포함하여 전달합니다.
카드사에서 준 카드 BIN 번호
마스킹되어 있을 수 있으며, 100% 신뢰는 불가합니다.
사용자가 선택한 계좌의 은행코드
사용자가 선택한 결제수단(payMethod)이 '토스머니'인 경우 토스가 정의한 은행코드를 전달합니다.
사용자가 선택한 계좌의 은행명
사용자가 선택한 계좌번호
계좌번호는 일부 마스킹을 포함할 수 있습니다.
Example Request
{
"action": "ACTIVATED",
"processedTs": "2020-04-01 12:34:11",
"userId": "TOSS-TEST-1",
//"displayId": "TEST_SERVICE_1",
"billingKey": "example-billingKey",
"payMethod": "TOSS_MONEY",
"accountBankCode": "88",
"accountBankName": "신한은행",
"accountNumber": "110******676"
}