웹훅 이벤트
토스페이먼츠에서 제공하는 웹훅 이벤트 목록입니다. 웹훅 연동 방법 및 재전송 정책은 웹훅 연결하기 가이드를 참고해주세요.
웹훅 헤더
토스페이먼츠 웹훅은 다음과 같은 헤더가 있습니다.
- tosspayments-webhook-transmission-time
웹훅이 발송된 시간입니다.
- tosspayments-webhook-transmission-retried-count
웹훅이 재전송된 횟수입니다. 웹훅 재전송 정책을 확인하세요.
- tosspayments-webhook-transmission-id
웹훅의 고유 식별자입니다.
- tosspayments-webhook-signature
payout.changed,seller.changed웹훅 헤더에만 포함되는 웹훅 서명입니다. 토스페이먼츠가 보낸 웹훅인지 검증할 수 있는 값입니다. 검증하는 방법은 아래와 같습니다.-
{WEBHOOK_PAYLOAD}:{tosspayments-webhook-transmission-time}값을 보안 키로 HMAC SHA-256 해싱하세요. -
웹훅 헤더에서
v1:뒤에오는 2개의 값을 모두 base64로 디코딩하세요. -
1번에서 해시값과 2번에서 디코딩한 값 중 하나가 일치하면 토스페이먼츠에서 보낸 올바른 웹훅이 맞습니다. 일치하지 않으면 토스페이먼츠에서 보낸 웹훅이 아니고 웹훅 데이터를 신뢰할 수 없습니다. 위에 있는 헤더를 예시로 들면, 아래 둘 중 하나의 값이
true이어야 합니다.
-
결제
PAYMENT_STATUS_CHANGED
카드, 계좌이체, 휴대폰, 상품권 결제 상태를 알려주는 웹훅입니다. 웹훅이 발송되는 결제 상태는 아래 그림에서 살펴보세요.
결제창이 유효한 30분 안에 구매자가 결제창에서 인증을 하지 않거나, 결제 인증이 유효한 10분 안에 상점에서 결제 승인 API를 호출하지 않으면 결제 상태가 EXPIRED로 변경됩니다.
구매자가 결제창을 닫으면 결제 상태가 바뀌지 않기 때문에 웹훅도 전송되지 않습니다.
자동결제는 결제 요청에 이어서 승인이 되기 때문에 결제가 완료됐을 때 웹훅을 전송하지 않습니다.
이벤트 본문
- eventType string
웹훅 이벤트 타입입니다.
- createdAt string
웹훅이 생성된 시간입니다.
yyyy-MM-dd'T'HH:mm:ss.SSSSSSISO 8601 형식입니다. - data object
상태가 변경된 Payment 객체입니다.
DEPOSIT_CALLBACK
가상계좌 결제 상태를 알려주는 웹훅입니다. 웹훅이 발송되는 결제 상태는 아래 그림에서 살펴보세요.
가상계좌 웹훅 연동 예제, 입금 테스트하는 방법 등 더 자세한 연동 방법은 가상계좌 웹훅 연동 가이드를 참고하세요.
고객의 계좌 송금 한도가 초과되었거나 네트워크 이슈 등으로 입금 오류가 일어나면 결제 상태가 DONE에서 WAITING_FOR_DEPOSIT으로 변경됩니다. 결제 고객에게 다시 입금하도록 안내해야 합니다.
버전 1.4까지는 입금 오류가 일어나면 결제 상태가 DONE에서 CANCELED로 변경됩니다. 마찬가지로 결제 고객에게 다시 입금하도록 안내해야 합니다.
만약 PAYMENT_STATUS_CHANGED, DEPOSIT_CALLBACK 이벤트를 모두 등록했다면 가상계좌 상태가 변경될 때 웹훅이 두 번 전송됩니다.
이벤트 본문
- createdAt string
웹훅이 생성된 시간입니다.
yyyy-MM-dd'T'HH:mm:ss.SSSSSSISO 8601 형식입니다. - secret string
가상계좌 웹훅 요청이 정상적인 요청인지 검증하는 값입니다. 결제 승인 API의 응답으로 돌아온
secret과 같으면 정상적인 요청입니다. - status string
결제 상태입니다.
- transactionKey string
상태가 변경된 가상계좌 거래를 특정하는 키입니다.
- orderId string
주문번호입니다. 자세한 결제 정보를 보고 싶다면
orderId로 결제 조회를 하세요.
CANCEL_STATUS_CHANGED
결제 취소 상태를 알려주는 웹훅입니다. 결제 취소가 성공하거나 실패했을 때 웹훅이 발송됩니다.
이벤트 본문
- eventType string
웹훅 이벤트 타입입니다.
- createdAt string
웹훅이 생성된 시간입니다.
yyyy-MM-dd'T'HH:mm:ss.SSSSSSISO 8601 형식입니다. - data object
상태가 변경된 Cancel 객체입니다.
브랜드페이
METHOD_UPDATED
브랜드페이 고객의 결제수단이 변경되면 웹훅이 전송됩니다.
이벤트 본문
- eventType string
웹훅 이벤트 타입입니다.
- createdAt string
웹훅이 생성된 시간입니다.
yyyy-MM-dd'T'HH:mm:ss.SSSSSSISO 8601 형식입니다. - data object
아래 세 가지 필드가 돌아옵니다.
customerKey: 상점에서 만든 고객의 고유 ID입니다.methodKey: 결제수단을 특정하는 키입니다.status: 결제수단의 상태입니다.ENABLED: 결제수단이 등록되어 사용할 수 있게 된 상태DISABLED: 결제수단이 삭제되어 사용할 수 없게 된 상태ALIAS_UPDATED: 등록되어 있는 결제수단의 별명이 변경된 상태
CUSTOMER_STATUS_CHANGED
브랜드페이 고객의 상태가 변경되면 웹훅이 전송됩니다.
이벤트 본문
- eventType string
웹훅 이벤트 타입입니다.
- createdAt string
웹훅이 생성된 시간입니다.
yyyy-MM-dd'T'HH:mm:ss.SSSSSSISO 8601 형식입니다. - data object
아래 세 가지 필드가 돌아옵니다.
customerKey: 상점에서 만든 고객의 고유 ID입니다.status: 고객의 브랜드페이 사용 관련 상태입니다.CREATED: 간편결제에 가입한 상태REMOVED: 간편결제에 탈퇴한 상태PASSWORD_CHANGED: 비밀번호를 변경한 상태ONE_TOUCH_ACTIVATED: 원터치결제를 활성화한 상태ONE_TOUCH_DEACTIVATED: 원터치결제를 비활성화한 상태
changedAt: 변경이 일어난 시점입니다.yyyy-MM-dd'T'HH:mm:ss±hh:mmISO 8601 형식입니다.
지급대행
payout.changed
지급대행 요청 상태가 COMPLETED, FAILED로 바뀌면 웹훅이 전송됩니다.
이벤트 본문
- eventType string
웹훅 이벤트 타입입니다. 지급대행 웹훅은
payout.changed입니다. - createdAt string
웹훅이 생성된 시간입니다.
yyyy-MM-dd'T'HH:mm:ss±hh:mmISO 8601 형식입니다. - version string
- eventId string
웹훅의 고유 식별자입니다.
- entityType string
웹훅의 고유 식별자입니다.
- entityBody object
상태가 변경된 Payout 객체입니다. 사용하는 API 버전에 따라 객체 필드가 다를 수 있습니다.
seller.changed
셀러의 상태가 PARTIALLY_APPROVED, KYC_REQUIRED, APPROVED로 바뀌면 웹훅이 전송됩니다. KYC 심사를 마친 셀러는 1년 또는 3년에 다시 심사를 받아야 됩니다. 그럼 셀러의 상태는 다시 KYC_REQUIRED로 바뀝니다.
이벤트 본문
- eventType string
웹훅 이벤트 타입입니다. 지급대행 웹훅은
seller.changed입니다. - createdAt string
웹훅이 생성된 시간입니다.
yyyy-MM-dd'T'HH:mm:ss±hh:mmISO 8601 형식입니다. - version string
- eventId string
웹훅의 고유 식별자입니다.
- entityType string
웹훅의 고유 식별자입니다.
- entityBody object
상태가 변경된 Seller 객체입니다. 사용하는 API 버전에 따라 객체 필드가 다를 수 있습니다.