토스페이 연동가이드

사용자가 토스 앱을 통해 빌링 등록을 '성공적'으로 완료한 경우 토스 서버는 가맹점이 설정한 resultCallback URL을 통해 결과를 전달합니다. 대부분의 자동결제 등록 실패에 대해서는 사용자의 재시도를 고려하여 실패 결과를 전달하지 않지만, 더 이상 등록을 진행할 수 없는 상태(재시도 불가)로 판단하면 실패 결과를 전달합니다. 예를 들면 CI(유저) 불일치로 등록이 차단되는 경우가 이에 해당합니다.

토스 쪽에서 삭제가 발생되는 경우 토스 pay Server에서 삭제(REMOVED) callback을 보낼 수 있음을 참고해야 합니다.
callback에 대한 응답의 HTTP status code가 200인 경우에만 '정상' 수신으로 간주하며, 그 외의 응답 코드는 미수신으로 실패한 것으로 인식하여 3분 간격으로 최대 4번 접근을 시도합니다.
빌링키 생성결과 callback의 Payload는 다음과 같습니다.

각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.

파라미터

actionstring

요청 처리에 따른 빌링키 상태를 전달합니다.

가능한 값:

ACTIVATEDREMOVED

ACTIVATED : 빌링키 활성화 완료. 빌링키 생성요청에 따라, 토스 → 가맹점으로 '정상처리'를 알리는 콜백 - REMOVED : 빌링키 삭제 완료. 토스 → 가맹점으로 빌링키 삭제를 요청할 수 있다. 그 때, '삭제완료' 상태를 알리는 콜백

processedTsstring

상태 처리시간. `action` 에 따라 각 상태의 처리시간을 전달합니다.

userIdstring

가맹점이 생성한 사용자 식별 값. 가맹점의 요청 값 그대로를 전달합니다.

displayIdstring

가맹점이 생성한 표시 가능한 빌링키 식별 값. 가맹점의 요청 값 그대로를 전달합니다.

billingKeystring

활성화/삭제 자동결제 사용자 빌링키

payMethodstring

사용자가 토스에서 인증한 결제수단. 선택한 결제수단에 따라 토스머니(`TOSS_MONEY`) 또는 카드(`CARD`)를 전달합니다.

가능한 값:

TOSS_MONEYCARD

cardMethodTypestring

승인된 카드의 타입을 구분. 선택한 결제수단에 따라 신용카드(`CREDIT`), 체크카드(`CHECK`), 선불카드(`PREPAYMENT`)를 전달합니다.

가능한 값:

CREDITCHECKPREPAYMENT

cardUserTypestring

카드 사용자 구분

가능한 값:

PERSONALPERSONAL_FAMILYCORP_PERSONALCORP_PRIVATECORP_COMPANY

PERSONAL : 본인 카드 - PERSONAL_FAMILY : 가족 카드 - CORP_PERSONAL : 법인지정 결제계좌 임직원 - CORP_PRIVATE : 법인 공용 - CORP_COMPANY : 법인지정 결제계좌 회사(하나카드만)

cardCompanyNointeger

사용자가 선택한 카드의 카드코드. 사용자가 선택한 결제수단(`payMethod`)이 '카드'인 경우 토스가 정의한 카드코드를 전달합니다.

cardCompanyNamestring

사용자가 선택한 카드의 카드사명. 사용자가 선택한 결제수단(`payMethod`)이 '카드'인 경우 카드사명을 함께 전달합니다.

cardNumberstring

사용자가 선택한 카드의 번호. 카드번호 16자리 중 중간자리는 마스킹됩니다.

cardNum4Printstring

사용자가 선택한 카드의 끝 4자리. 사용자가 선택한 결제수단(`payMethod`)이 '카드'인 경우 카드번호를 포함하여 전달합니다.

cardBinNumberstring

카드사에서 준 카드 BIN 번호. 마스킹되어 있을 수 있으며, 100% 신뢰는 불가합니다.

accountBankCodestring

사용자가 선택한 계좌의 은행코드. 사용자가 선택한 결제수단(`payMethod`)이 '토스머니'인 경우 토스가 정의한 은행코드를 전달합니다.

accountBankNamestring

사용자가 선택한 계좌의 은행명. [은행코드 리스트](/guide/bank-code)

accountNumberstring

사용자가 선택한 계좌번호. 계좌번호는 일부 마스킹을 포함할 수 있습니다.

예제

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"
}

빌링키 처리결과 callback

파라미터

예제

목차