결제 운영/웹훅 연동
목차

웹훅은 데이터가 변경되었을 때 상점 서버에서 실시간으로 알림을 받을 수 있는 기능입니다. 웹훅을 연동해서 결제 상태 변경, 지급대행 실행, 브랜드페이 고객 결제수단 업데이트와 같은 변경 사항을 실시간으로 받아보세요.

웹훅 발송은 상점아이디(MID)별로 따로 발송됩니다.

웹훅 사용하기

1. 웹훅 이벤트 타입을 알아보세요

웹훅으로 등록할 수 있는 이벤트 타입은 아래와 같습니다. 웹훅 본문과 자세한 설명은 각 이벤트 타입을 선택해서 살펴보세요.

이벤트 타입설명
PAYMENT_STATUS_CHANGED결제 상태 변경 이벤트입니다. 모든 결제수단에 사용 가능합니다.
DEPOSIT_CALLBACK가상계좌 입금 및 입금 취소 이벤트입니다.
PAYOUT_STATUS_CHANGED서브몰 지급대행 성공 또는 실패 이벤트입니다.
METHOD_UPDATED브랜드페이 고객 결제수단 변경 이벤트입니다.
CUSTOMER_STATUS_CHANGED브랜드페이 고객 상태 변경 이벤트입니다.

2. 웹훅 이벤트를 등록하세요

개발자센터 웹훅 페이지에서 웹훅 등록하기를 누르면 웹훅 이벤트 등록 팝업창이 열립니다. 웹훅 이름, 웹훅 URL을 입력하고 등록할 이벤트를 선택하세요. 마지막으로 '등록하기' 를 누르면 웹훅이 등록됩니다.

웹훅 목록에서 잘 등록되었는지 확인하세요. 결제 상태가 변경되어 등록한 이벤트가 발생하면 웹훅 URL로 웹훅 이벤트가 전송됩니다. 웹훅은 상세 페이지에서 삭제할 수 있습니다.

개발자센터 웹훅 설정 페이지

웹훅 URL은 온라인에서 접근할 수 있는 주소를 등록해야 합니다. 로컬 개발 환경은 외부에서 접근할 수 없기 때문에 로컬 서버 포트가 포함된 URL은 웹훅으로 등록할 수 없습니다.

혹은 로컬 개발 환경에 접근할 수 있도록 도와주는 도구를 사용해서 테스트할 수 있습니다.

ngrok을 사용하면 로컬에서 실행된 서버를 외부에서 안전하게 접근할 수 있습니다. 내 로컬 서버 포트에 접근할 수 있는 URL을 만들고 아래와 같이 웹훅을 테스트해보세요.

ngrok 예제 이미지

  1. ngrok을 다운로드하세요.
  2. 터미널에서 ngrok http 8080와 같이 내가 사용할 로컬 서버 포트 번호를 커맨드에 추가해 실행하세요.
  3. 서버 코드에 웹훅 엔드포인트를 추가하고 원하는 로직을 작성하세요.
  4. ngrok 콘솔을 실행했다면 localhost:8080로 포워딩할 수 있도록 생성된 URL(Forwarding)를 개발자센터 웹훅 페이지에 등록하세요. 3단계에서 만든 웹훅 엔드포인트를 ngrok으로 생성한 URL 뒤에 추가해서 등록해야 합니다.
  5. 테스트 결제를 해보세요. 등록한 URL로 웹훅이 발송됩니다. ngrok 인스펙터(Web Interface)에서 아래와 같이 이벤트 데이터가 들어온 것을 확인할 수 있습니다.

ngrok 인스펙터 예제 이미지

이벤트는 HTTP POST 메서드로 전달되는 JSON 파일입니다. 서버에서 JSON을 처리할 수 있는지 확인해주세요. HTTP도 지원하지만 보안이 강화된 HTTPS 통신을 권장합니다.

3. 웹훅 전송 기록을 확인하세요

개발자센터 웹훅 목록에서 등록한 웹훅을 선택하면 웹훅 상세 정보와 전송 기록을 확인할 수 있습니다.

웹훅 전송 기록은 등록한 이벤트의 가장 최근 전송 상태를 보여줍니다. 즉, 하나의 전송 기록은 이벤트가 발생한 뒤의 상태 변화를 표현합니다. 이벤트 발생 시간을 선택하면 해당 이벤트의 본문을 볼 수 있습니다.

전송 상태는 '전송 중', '성공', '실패' 중 하나입니다.

웹훅 전송 기록 예제 이미지

웹훅 재전송 정책

웹훅 전송 후 응답으로 HTTP 2xx 코드가 돌아오면 전송 상태는 '성공'입니다. 최초의 웹훅 전송이 실패하면 최대 7회(최초 전송으로부터 3일 19시간 후)까지 웹훅을 재전송합니다.

1회부터 6회까지 웹훅 전송이 실패해도 웹훅 상태는 '전송 중'입니다. 7회 웹훅 전송이 실패하면 웹훅 상태가 '실패'로 변경됩니다.

웹훅 재전송

재전송 횟수재전송 간격(분)
11
24
316
464
5256
61024
74096

'전송 중'일 때 '다시 시도' 를 누르면 진행 중이던 재전송 시도는 무효화되고 새로운 1회 요청이 시도됩니다. 웹훅 전송이 계속 실패한다면 등록한 웹훅 URL의 포트 번호에 방화벽 설정이 허용되어 있는지 확인해보세요. 7회 전송까지 실패하면 이메일로 이벤트 정보를 알려드립니다.

이벤트 타입

PAYMENT_STATUS_CHANGED

카드, 계좌이체, 휴대폰, 상품권 결제 상태를 알려주는 웹훅입니다. 웹훅이 발송되는 결제 상태는 아래 그림에서 살펴보세요.

유효 시간(30분) 안에 고객이 결제창에서 인증을 하지 않거나, 고객의 결제 인증 이후 상점에서 결제 승인 API를 호출하지 않으면 결제 상태가 EXPIRED로 변경됩니다.

고객이 결제창을 닫으면 결제 상태가 바뀌지 않기 때문에 웹훅도 전송되지 않습니다.

자동결제는 결제 요청에 이어서 승인이 되기 때문에 결제가 완료됐을 때 웹훅을 전송하지 않습니다.

이벤트 본문

예시
JSON
{
"eventType": "PAYMENT_STATUS_CHANGED",
"createdAt": "2022-01-01T00:00:00.000000",
"data": {
"mId": "tosspayments",
"version": "2022-11-16",
"lastTransactionKey": "B7103F204998813B889C77C043D09502",
"paymentKey": "",
"orderId": "",
"status": "DONE",
"requestedAt": "2022-08-05T12:56:00+09:00",
"approvedAt": "2022-08-05T12:56:21+09:00",
"useEscrow": false,
"card": {
"issuerCode": "61",
"acquirerCode": "31",
"number": "48902300****406*",
"installmentPlanMonths": 0,
"amount": 10000
//...
}
//...
}
}
  • eventType 필수 · string

    웹훅 이벤트 타입입니다.

  • createdAt 필수 · string

    웹훅이 생성된 시간입니다. yyyy-MM-dd'T'HH:mm:ss.SSSSSS ISO 8601 형식입니다.

  • data 필수 · object

    상태가 변경된 Payment 객체입니다.

DEPOSIT_CALLBACK

가상계좌 결제 상태를 알려주는 웹훅입니다. 웹훅이 발송되는 결제 상태는 아래 그림에서 살펴보세요.

가상계좌 웹훅 연동 예제, 입금 테스트하는 방법 등 더 자세한 연동 방법은 가상계좌 웹훅 연동 가이드를 참고하세요.

고객의 계좌 송금 한도가 초과되었거나 네트워크 이슈 등으로 입금 오류가 일어나면 결제 상태가 DONE에서 WAITING_FOR_DEPOSIT으로 변경됩니다. 결제 고객에게 다시 입금하도록 안내해야 합니다.

버전 1.4까지는 입금 오류가 일어나면 결제 상태가 DONE에서 CANCELED로 변경됩니다. 마찬가지로 결제 고객에게 다시 입금하도록 안내해야 합니다.

이벤트 본문

예시
JSON
{
"createdAt": "2022-01-01T00:00:00.000000",
"secret": "",
"status": "DONE",
"transactionKey": "9FF15E1A29D0E77C218F57262BFA4986",
"orderId": ""
}
  • createdAt 필수 · string

    웹훅이 생성된 시간입니다. yyyy-MM-dd'T'HH:mm:ss.SSSSSS ISO 8601 형식입니다.

  • secret 필수 · string

    가상계좌 웹훅 요청이 정상적인 요청인지 검증하는 값입니다. 결제 승인 API의 응답으로 돌아온 secret과 같으면 정상적인 요청입니다.

  • status 필수 · string

    결제 상태입니다.

  • transactionKey 필수 · string

    상태가 변경된 가상계좌 거래를 특정하는 키입니다.

  • orderId 필수 · string

    주문 ID입니다.

PAYMENT_STATUS_CHANGED, DEPOSIT_CALLBACK 이벤트를 둘 다 등록했을 때 가상계좌 상태가 변경되면 웹훅도 두 번 전송됩니다.

PAYOUT_STATUS_CHANGED

지급대행 요청 상태가 COMPLETED, FAILED로 변경되면 웹훅이 전송됩니다. 자세한 상태 설명은 status에서 확인하세요.

이벤트 본문

예시
JSON
{
"eventType": "PAYOUT_STATUS_CHANGED",
"createdAt": "2022-01-01T00:00:00.000000",
"data": {
"payoutKey": "",
"subMallId": "testmall100",
"payoutDate": "20220103",
"payoutAmount": 10000,
"requestedAt": "20220101100130",
"account": {
"bankCode": "03",
"accountNumber": "00123412341234",
"holderName": null
},
"status": "COMPLETED",
"metadata": null,
"failure": null,
"transferSummary": null
}
}
  • eventType 필수 · string

    웹훅 이벤트 타입입니다.

  • createdAt 필수 · string

    웹훅이 생성된 시간입니다. yyyy-MM-dd'T'HH:mm:ss.SSSSSS ISO 8601 형식입니다.

  • data 필수 · object

    상태가 변경된 Payout 객체입니다.

METHOD_UPDATED

브랜드페이 고객의 결제수단이 변경되면 웹훅이 전송됩니다.

이벤트 본문

예시
JSON
{
"eventType": "METHOD_UPDATED",
"createdAt": "2022-05-12T00:00:00.000000",
"data": {
"customerKey": "",
"methodKey": "",
"status": "ENABLE"
}
}
  • eventType 필수 · string

    웹훅 이벤트 타입입니다.

  • createdAt 필수 · string

    웹훅이 생성된 시간입니다. yyyy-MM-dd'T'HH:mm:ss.SSSSSS ISO 8601 형식입니다.

  • data 필수 · object

    아래 세 가지 필드가 돌아옵니다.

    • customerKey: 상점에서 만든 고객의 고유 ID입니다.
    • methodKey: 결제수단을 특정하는 키입니다.
    • status: 결제수단의 상태입니다.
      • ENABLED: 결제수단이 등록되어 사용할 수 있게 된 상태
      • DISABLED: 결제수단이 삭제되어 사용할 수 없게 된 상태
      • ALIAS_UPDATED: 등록되어 있는 결제수단의 별명이 변경된 상태

CUSTOMER_STATUS_CHANGED

브랜드페이 고객의 상태가 변경되면 웹훅이 전송됩니다.

이벤트 본문

예시
JSON
{
"eventType": "CUSTOMER_STATUS_CHANGED",
"createdAt": "2022-01-01T00:00:00.000000",
"data": {
"customerKey": "",
"status": "PASSWORD_CHANGED",
"changedAt": "2022-01-01T00:00:00+09:00"
}
}
  • eventType 필수 · string

    웹훅 이벤트 타입입니다.

  • createdAt 필수 · string

    웹훅이 생성된 시간입니다. yyyy-MM-dd'T'HH:mm:ss.SSSSSS ISO 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:mm ISO 8601 형식입니다.
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    실시간 문의|이메일 보내기