웹훅 이벤트

결제 상태 변경과 정산 완료를 상점 서버에 알려주는 웹훅 이벤트입니다.

웹훅을 연동하려면 수신할 URL을 help@atones.co.kr로 보내주세요. 추가 계약(무료) 후 등록한 URL로 웹훅을 발송합니다.

수신과 검증

웹훅은 HTTP POST 요청으로 전달합니다. 수신 내용을 저장한 뒤 2XX로 응답해주세요. 모든 2XX 응답을 성공으로 처리하며, 4XX·5XX 응답이나 통신 실패로 전송에 실패한 웹훅은 자동 재전송하지 않습니다.

동일한 거래의 웹훅을 여러 번 받거나 상태가 변경된 순서와 다르게 받을 수 있습니다. 중복 수신을 구분하고, 조회 API에서 확인한 거래 상태를 기준으로 주문과 정산 내역을 반영해주세요.

결제 내역은 웹훅의 intentKey로 결제 조회 API를 호출해 확인하세요. 주문번호로 조회하면 해당 주문의 최신 결제 시도를 반환합니다. 정산 내역은 settlementId로 정산 조회 API를 호출해 확인하세요. 수신에 실패한 거래도 조회 API로 대조해주세요.

웹훅 헤더

candypay-webhook-transmission-time

웹훅을 발송한 시각입니다. 한국 표준시(+09:00)를 포함한 ISO 8601 형식으로 전달합니다.

candypay-webhook-transmission-time: 2024-09-05T12:19:21+09:00

candypay-webhook-signature

정산 웹훅(SETTLEMENT_CREATED)의 서명입니다. 캔디페이가 보낸 웹훅인지 검증할 때 사용합니다.

candypay-webhook-signature: v1:<Base64 HMAC-SHA256>

다음 순서로 서명을 검증하세요.

1. {WEBHOOK_PAYLOAD}:{candypay-webhook-transmission-time} 값을 보안 키로 HMAC-SHA256 해싱하세요. WEBHOOK_PAYLOAD는 JSON 파싱 전의 UTF-8 본문 원문입니다. 본문과 발송 시각은 수신한 값을 그대로 사용하세요.
2. 서명 헤더에서 v1: 뒤의 값을 Base64로 디코딩하세요. ,로 구분된 서명이 여러 개 있으면 각각 디코딩하세요.
3. 1번에서 해시한 값과 2번에서 디코딩한 값 중 하나가 일치하면 캔디페이에서 보낸 올바른 웹훅이 맞습니다.

결제

PAYMENT_STATUS_CHANGED

승인 완료·부분취소·전액취소 시 발송하는 결제 상태 변경 이벤트입니다.

발송 대상은 DONE, PARTIAL_CANCELED, CANCELED 상태입니다. 각 상태의 의미는 결제 상태를 확인하세요.

본문에는 발송 시 조회한 PaymentIntent 객체를 담습니다.

이벤트 본문

{
  "eventType": "PAYMENT_STATUS_CHANGED",
  "createdAt": "2022-01-01T00:00:00.000Z",
  "data": {
    /** PaymentIntent 객체 */
  }
}

data는 PaymentIntent 객체입니다.

정산

SETTLEMENT_CREATED

정산 완료 시 발송하는 이벤트입니다. settlementId로 정산 내역을 확인할 수 있습니다.

{
  "eventType": "SETTLEMENT_CREATED",
  "createdAt": "2022-01-01T00:00:00.000Z",
  "data": {
    /** Settlement 객체 */
  }
}

data는 Settlement 객체입니다. https://docs.tosspayments.com/reference/using-api/api-keys#api-%EA%B0%9C%EB%B3%84-%EC%97%B0%EB%8F%99-%ED%82%A4