웹훅(Webhook) 연동하기

입금이나 결제취소로 인해 변경된 결제 상태를 알고 싶다면 웹훅 URL을 등록해두세요. 결제 상태가 변경되면 토스페이먼츠 서버에서 등록된 URL로 이벤트를 보내줍니다.

웹훅은 특정 이벤트가 발생했을 때 가맹점 서버를 호출하는 기능입니다. 가맹점에서 웹훅 콜백 URL을 미리 등록해두면 결제 상태가 변경되는 이벤트가 발생했을 때 알림을 받을 수 있습니다.

토스페이먼츠 웹훅은 이런 과정에서 사용됩니다.

1. 고객이 입금하거나 결제를 취소하는 등 결제 상태 변경 이벤트가 발생합니다.
2. 토스페이먼츠 서버가 등록된 콜백 URL에 HTTP 요청을 보내서 결제 상태가 변경된 것을 알려줍니다.
3. 가맹점 서버에서 토스페이먼츠에서 보내준 데이터를 통해 결제 상태를 확인합니다.

가맹점 서버에서 웹훅 URL을 만든 뒤 토스페이먼츠 홈페이지 > 내 상점 > 개발 정보 페이지에서 등록합니다.

토스페이먼츠에서 지원하는 웹훅 종류는 두가지입니다. 가상계좌를 연동했을 때 필수적으로 추가해야 하는 가상계좌 입금 알림 웹훅, 그리고 결제수단과 상관없이 선택적으로 사용할 수 있는 일반 웹훅입니다.

가상계좌는 입금완료 시점을 알아야 하는 결제수단이기 때문에 가상계좌를 연동했다면 가상계좌 입금 알림 웹훅을 반드시 등록해야합니다. 고객이 금액을 입금했거나 입금을 취소해서 결제 상태가 변경되면 토스페이먼츠 서버가 가상계좌 입금 알림 콜백 URL을 호출해서 알려줍니다.

요청 본문 형태는 아래와 같습니다.

{
  "secret": "ps_ZORzdMaqN3weJkOmRgNr5AkYXQGw",
  "status": "DONE",
  "orderId": ""
}

• secret: 콜백 요청이 정상적인 요청인지 검증하기 위한 값입니다. 이 값이 결제승인 API의 응답으로 돌아온 secret과 같으면 정상적인 요청입니다.

• status: 입금 처리 상태입니다. 고객이 가상계좌에 입금하면 값이 DONE입니다. 입금이 취소되면 값이 CANCELED 입니다.

  • DONE : 가상계좌에 입금 되었습니다.
  • CANCELED : 가상계좌 입금이 취소되었습니다.
  • PARTIAL_CANCELED : 가상계좌 입금 부분 취소가 이루어졌습니다.

• orderId: 가맹점에서 주문건에 대해 발급한 고유 ID입니다.

고객 계좌의 송금 한도, 네트워크 이슈 등으로 인해 입금 처리 상태가 달라진 콜백이 다시 돌아오는 경우가 있습니다. 예를 들어 입금 처리 상태가 DONE인 콜백을 받은 뒤 CANCELED로 변경된 결제 상태의 콜백이 돌아온 경우, 결제 완료된 기록을 입금 전 상태로 되돌린 뒤 다시 처리해야 합니다.

웹훅 콜백은 결제수단과 상관없이 가맹점에서 결제 상태를 알고 싶을 때 사용합니다. 단, 카드 자동결제(Billing)는 서버에서 직접 결제 요청을 하는 결제 방식이므로 웹훅을 지원하지 않습니다.

다른 결제수단과 달리 가상계좌에는 고객이 금액을 입금하기 전까지 대기 중인 상태를 나타내는 WAITING_FOR_DEPOSIT이 있습니다. 가상계좌 결제에서는 WAITING_FOR_DEPOSIT 상태도 콜백으로 받을 수 있습니다.

• DONE : 결제가 완료되었습니다.
• CANCELED : 결제가 취소되었습니다
• PARTIAL_CANCELED : 결제 부분 취소가 이루어졌습니다.
• WAITING_FOR_DEPOSIT : 가상계좌 입금 대기 상태입니다.
  • 결제수단이 가상계좌일 때만 수신합니다. 가상계좌가 발급되면 결제 상태는 바로 입금 대기 상태가 됩니다.

웹훅 이벤트는 HTTP POST 메서드를 사용해서 JSON형태로 전달됩니다. 서버에서 JSON을 처리할 수 있는지 확인해주세요.

결제 상태가 변경되면 등록해 둔 웹훅 URL에 다음과 같은 형태의 이벤트 본문을 보내줍니다. HTTP도 지원하지만 보안을 위해 HTTPS로 통신하는 것을 권장합니다.

{
  "eventType": "PAYMENT_STATUS_CHANGED",
  "data": {
    "paymentKey": "5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6",
    "status": "DONE",
    "orderId": ""
  }
}

• eventType: 웹훅의 이벤트 타입입니다. 결제 상태를 확인하기 위한 이벤트 타입인 PAYMENT_STATUS_CHANGED를 고정으로 사용합니다.
• data
  • paymentKey: 결제 건에 대한 고유한 키 값입니다.
  • status: 결제 상태입니다.
  • orderId: 가맹점에서 주문건에 대해 발급한 고유 ID입니다.

콜백 요청에 대한 응답으로 HTTP 200 OK이 돌아올 경우 성공으로 판단하며, 이외에는 실패로 판단합니다. 실패할 경우 성공할 때까지 몇 차례 재시도합니다.