서버로 웹훅 수신하기

결제 결과를 부트페이 서버에서 가맹점 서버로 통지해요. 클라이언트 승인 시에도done이벤트를 통해 결과 데이터가 전달되지만, 클라이언트 특성상 인터넷 환경이나 기타 상황에 의해 데이터가 유실될 수 있어요. 만약 클라이언트에서 받은 결제 결과를 서버로 전달하여 처리한다면, 실제 결제가 되었음에도 불구하고 결제가 되지 않은 것으로 구매자에게 잘못 표시되는 문제가 발생할 수 있어요.

웹훅이 발송되는 시점

결제 완료/취소(부분 취소 포함) 되었을 때

가상계좌 발급 / 입금 완료되었을 때

예약된 결제가 실행(결제 완료/실패)되었을 때

그 외 모든 결제 요청(서버 승인, 빌링키 결제 등)에 대한 결과도 웹훅으로 통지돼요.

결제창 닫힘, 시간 만료 통지 받기

결제창이 닫히거나 특정 시간(예: 30분)이 지나 결제를 만료 처리하고 싶을 경우 웹훅을 통해 통지를 받을 수 있어요. 이 기능은 예약 서비스를 제공하는 경우 유용해요.

결제 요청시payload.extra.common_event_webhook = true;옵션을 추가하면 통지를 받을 수 있으며, 결제 만료시간은payload.extra.timeout = 30;(분)으로 설정할 수 있어요.

결제 승인 실패 통지 받기

결제 승인이 실패했을 때 웹훅을 통해 통지를 받을 수 있어요. 설정 방법은 2가지입니다.

관리자에서 Error Webhook 받기를 활성화 합니다.

결제 요청시payload.extra.enable_error_webhook = true;옵션을 추가하면 통지를 받을 수 있습니다.

웹훅 수신 설정하기

웹훅은HTTP POST로 전송됩니다. 웹훅을 받을 URL과 Content-Type을 설정할 수 있습니다. 설정 방법은 2가지 입니다.

결제 요청시 설정하기

자동결제 사용시에만 유효합니다. 서버사이드 SDK로 결제 요청시payload.feedback_url,payload.content_type옵션을 추가하면 통지를 받을 수 있습니다. 값을 설정하지 않을 경우 웹훅은 관리자에서 설정한 값으로 전달됩니다.

관리자에서 설정하기

관리자에서 웹훅을 받도록 설정할 수 있습니다.

1. 설정 > 개발자센터 > 웹훅설정메뉴로 이동한 뒤 "결제웹훅" 탭을 선택합니다

2.Webhook 설정하기버튼을 누른 뒤Webhook URL,수신 받을 Content-Type,Error Webhook 수신,Webhook 최대 통지수를 설정합니다.

웹훅 설정 예시화면

웹훅 수신하기

위에서 설정한 가맹점 서버로 웹훅이 전달됩니다. 가맹점 서버에서는 정상적으로 웹훅이 수신되었는지 확인할 필요가 있습니다.

웹훅 수신 응답하기

결제가 완료되거나 발송 조건에 해당하면 설정된 가맹점 서버로 웹훅이 전달됩니다. 만약 웹훅이 수신되지 않는다면, 먼저 가맹점 웹서버 로그를 살펴봐주세요. 로그상 301 Moved Permanently 또는 500 Internal Server Error가 발생하면 웹훅이 수신되지 않습니다.

웹훅을 정상적으로 수신하였다면, HTTP Content-Type은application/json의 형태로{"success":true}를 응답하면, 부트페이 웹훅 서버에서 이를 확인하고 더 이상 웹훅을 보내지 않습니다. 만약 위의 값으로 응답하지 않으면 부트페이 웹훅 서버에서 일정 시간 후 웹훅을 재발송합니다.

관리자에서 확인하기

관리자 결제내역에서 웹훅이 전송되었는지 확인할 수 있습니다. 해당 결제건 우측 상세보기에서 웹훅 전송 여부와 응답하신 값을 살펴보실 수 있습니다.

관리자 결제내역 예시화면

재통지 요청하기

관리자 결제내역에서 재통지를 요청할 수 있습니다. 해당 결제건 우측 상세보기의 웹훅 메뉴에서 재통지를 요청할 수 있습니다. 재통지 요청 버튼이 보이지 않으시다면, 결제 전 웹훅이 설정되지 않은 상태이므로 해당 건은 웹훅을 수신할 수 없습니다.

관리자 결제내역내 웹훅 재요청 화면

웹훅 수신 예시

응답 파라메터

webhook_typestring

어떤 웹훅인지 구분하는 값입니다. * SDK 5.0.0부터 전달되는 값입니다

PAYMENT_COMPLETED	결제 완료
PAYMENT_CANCELLED	모든 금액의 결제 취소 ( 부분취소시에 잔액이 없는 취소의 경우에도 해당 )
PAYMENT_PARTIAL_CANCELLED	부분취소
PAYMENT_VIRTUAL_ACCOUNT_ISSUED	가상계좌 발급
PAYMENT_CONFIRM_FAILED	결제 승인 실패
PAYMENT_CANCEL_FAILED	결제 취소 실패
PAYMENT_REQUEST_FAILED	결제 요청 실패
PAYMENT_EXPIRED	결제 이탈 혹은 결제창 유효시간 만료
ERROR	그외 기타 에러

receipt_idstring
부트페이에서 부여하는 영수증 ID로 고유한 값을 가집니다. 결제 요청 시 생성되며, confirm, done, error 이벤트 및 관리자 페이지의 결제내역에서 확인할 수 있습니다. 데이터베이스에 반드시 저장해야 합니다.
order_idstring
결제 요청 시 가맹점에서 보낸 주문 ID입니다. 중복 결제를 방지하기 위해 사용될 수 있습니다.
pricenumber
결제 요청 및 승인된 금액입니다.
tax_freenumber
비과세 요청 및 승인된 금액입니다. 전체 price 중 비과세 금액만 지정합니다.
cancelled_pricenumber
결제 취소된 금액입니다. 최초 결제 완료 시에는 0원으로 표시됩니다.
cancelled_tax_freenumber
비과세 취소된 금액입니다. 최초 결제 완료 시에는 0원으로 표시됩니다.
order_namestring
결제 요청 시 전달된 판매 상품명입니다.
company_namestring
부트페이에 등록된 가맹점명입니다.
gateway_urlstring
PG로 요청된 부트페이 URL입니다. 이 값은 부트페이 내부적으로 사용되며, PG사에 referer로 전달됩니다.
metadatahash
결제 요청 시 전달된 메타데이터입니다. 전송된 데이터는 그대로 반환됩니다.
sandboxboolean
true는 테스트 결제 모드, false는 실제 결제 모드입니다.
pgstring
결제가 완료된 PG사의 이름입니다.
methodstring
결제에 사용된 결제 수단의 이름입니다.
method_symbolstring
결제 수단의 영문 심볼입니다.
method_originstring
결제 완료 시 원본 결제 수단명입니다.
ex) 카드자동결제는 method_origin이 카드자동, method가 카드로 표시됩니다.
method_origin_symbolstring
원본 결제 수단의 영문 심볼입니다.
currencystring
결제 완료 시 사용된 통화입니다. 예: KRW는 원화, USD는 달러입니다.
purchased_atdate
결제 완료 시간입니다. * PG에서 제공하는 데이터입니다.
cancelled_atdate
결제 취소 시간입니다. * PG에서 제공하는 데이터입니다.
requested_atdate
결제가 최초 요청된 시간입니다. ISO 8601형식으로 제공됩니다. * 부트페이 서버 시간 기준입니다.
receipt_urlstring
PG사 또는 부트페이에서 제공하는 영수증 URL입니다.
statusnumber
현재 결제 상태입니다.
- -61
  현금영수증 발행 취소가 실패한 상태입니다.
- -60
  현금영수증 발행이 실패한 상태입니다.
- -40
  자동결제 빌링키 발급이 실패한 상태입니다.
- -11
  자동결제 빌링키 발급이 취소된 상태입니다.
- -4
  결제 요청이 실패된 상태입니다.
- -2
  결제 승인 실패로 오류가 발생된 상태입니다.
- 0
  결제가 최초로 생성되어 요청이 대기 중인 상태입니다.
- 1
  결제가 완료된 상태입니다. 부분취소가 된 상태에서 전체금액이 취소되지 않았다면, 결제완료 상태입니다.
- 2
  결제 승인 중인 상태입니다. 분리 옵션으로 클라이언트 또는 서버 승인 전의 상태입니다.
- 4
  PG로 결제 승인이 요청된 상태이며, 부트페이 내부에서 사용되는 값입니다.
- 5
  가상계좌 발급 및 입금 대기 상태입니다.
- 11
  자동결제를 위한 빌링키 발급이 완료된 상태입니다.
- 12
  본인 인증이 완료된 상태입니다.
- 20
  결제 취소가 된 상태입니다. 결제된 금액이 전액 취소되면 결제 취소 상태가 됩니다.
- 40
  자동결제를 위한 빌링키 발급 준비 상태입니다.
- 41
  자동결제 빌링키 발급 이전 상태입니다. 생체인증, 비밀번호, 위젯 시나리오에서 서버승인 전 상태이기도 합니다.
- 42
  자동결제를 위한 빌링키 발급 성공 상태입니다.
- 50
  본인 인증 시작 준비 상태입니다.
- 60
  현금영수증을 별도 발행 시, 현금영수증 발행이 완료된 상태입니다.
- 61
  현금영수증 별도 발행 시, 현금영수증 발행이 취소된 상태입니다.
escrow_datahash
에스크로 결제 정보입니다. 에스크로 결제가 아닐 경우 이 값은 없습니다.
- statusnumber
  에스크로 진행 상태입니다.
- escrow_status_localestring
  에스크로 진행 상태를 요청 언어로 표시된 값입니다.
- shipping_started_atdate
  배송 시작 시간입니다.
- receipt_confirmed_atdate
  구매자가 배송을 확인하고 구매 승인한 시간입니다.
card_datahash
카드 결제 시 전달되는 데이터입니다.
- tidstring
  PG에서 발급한 결제 고유 식별 ID입니다. 문의 시 이 값을 사용하세요.
- card_approve_nostring
  카드사에서 전달하는 승인 번호입니다.
- card_nostring
  결제 승인 시 마스킹 처리된 카드 번호입니다.
- card_quotastring
  구매자가 선택한 카드 할부 개월 수입니다.
  범위: 00, 02, 03, 04, 05, 06, 07, 08 등
- card_company_codestring
  PG사에서 정의한 카드사 코드입니다.
- card_companystring
  결제 완료된 카드사의 이름입니다.
- card_interest일부 PG만 제공string
  카드 무이자 할부 개월 수입니다.
- card_type일부 PG만 제공string
  결제 완료된 카드의 종류입니다.
  0: 신용카드
  1: 체크카드
- receipt_url다날, 나이스페이만 제공string
  PG에서 제공하는 카드 영수증 URL입니다.
- card_owner_type일부 PG만 제공string
  카드 소유자 유형입니다.
  1: 개인카드
  2: 법인카드
  3: 해외카드
- point일부 PG만 제공number
  결제 시 사용된 카드사 포인트 금액입니다.
- cancelled_point일부 PG만 제공number
  결제 취소된 누적 포인트입니다.
- coupon일부 PG만 제공number
  결제 시 사용된 카드사 쿠폰 금액입니다.
- cancelled_coupon일부 PG만 제공number
  결제 취소된 누적 쿠폰 금액입니다.
- cancel_tid일부 PG만 제공string
  결제 취소 시 PG사에서 발급한 고유 식별 ID입니다.
phone_datahash
휴대폰 결제 시 전달되는 데이터입니다.
- tidstring
  PG에서 발급한 결제 고유 식별 ID입니다. 문의 시 이 값을 사용하세요.
- auth_no일부 PG만 제공string
  휴대폰 소액결제 승인 번호입니다.
- phone일부 PG만 제공string
  소액결제된 휴대폰 번호입니다.
- receipt_url나이스페이 제공string
  PG에서 제공하는 영수증 URL입니다.
bank_datahash
실시간 계좌이체 시 전달되는 데이터입니다.
- tidstring
  PG에서 발급한 결제 고유 식별 ID입니다. 문의 시 이 값을 사용하세요.
- bank_codestring
  공통 은행 코드입니다.
- bank_namestring
  계좌이체가 진행된 은행 이름입니다.
- bank_account일부 PG만 제공string
  계좌이체된 계좌 번호입니다.
- bank_usernamestring
  계좌이체된 계좌의 계좌주 이름입니다.
- cash_receipt_typestring
  계좌이체 시 발행된 현금영수증 유형입니다.
  0 : 소득공제
  1 : 지출증빙
- cash_receipt_nostring
  발행된 현금영수증 번호입니다.
- cash_receipt_tidstring
  PG사에서 발급한 고유 현금영수증 TID입니다.
- receipt_url나이스페이 제공string
  PG에서 제공하는 영수증 URL입니다.
- cash_receipt_url나이스페이 제공string
  PG에서 제공하는 현금영수증 발행 URL입니다.
vbank_datahash
가상계좌 발급 또는 결제 완료 시 전달되는 데이터입니다.
- tidstring
  PG에서 발급한 결제 고유 식별 ID입니다. 문의 시 이 값을 사용하세요.
- bank_namestring
  가상계좌가 발급된 은행 이름입니다.
- bank_accountstring
  입금해야 할 가상계좌 번호입니다.
- bank_usernamestring
  가상계좌의 계좌주 이름입니다. 보통 가맹점명이나 PG사 대표 이름으로 노출됩니다.
- expired_atdate
  가상계좌 입금 기한입니다. 이 시간 이후에는 계좌번호로 입금이 불가능합니다.
- sender_name일부 PG만 제공string
  입금 완료 후 입금자명으로 통지됩니다.
- cash_receipt_typestring
  계좌이체 시 발행한 현금영수증 유형입니다.
  0 : 소득공제
  1 : 지출증빙
- cash_receipt_nostring
  발행된 현금영수증 번호입니다.
- cash_receipt_tidstring
  PG사에서 발급한 고유 현금영수증 TID입니다.
- receipt_url나이스페이 제공string
  PG에서 제공하는 영수증 URL입니다.
- cash_receipt_url나이스페이 제공string
  PG에서 제공하는 현금영수증 발행 URL입니다.
kakao_money_data카카오페이 카드결제 시 card_data로 전달됩니다hash
카카오머니 결제 시 전달되는 데이터입니다.
- tidstring
  PG에서 발급한 결제 고유 식별 ID입니다. 문의 시 이 값을 사용하세요.
naver_point_data네이버페이 카드결제 시 card_data로 전달됩니다hash
네이버페이 포인트 결제 시 전달되는 데이터입니다.
- tidstring
  PG에서 발급한 결제 고유 식별 ID입니다. 문의 시 이 값을 사용하세요.
payco_point_data페이코 카드결제 시 card_data로 전달됩니다hash
페이코 포인트 결제 시 전달되는 데이터입니다.
- tidstring
  PG에서 발급한 결제 고유 식별 ID입니다. 문의 시 이 값을 사용하세요.
toss_point_data토스 카드결제 시 card_data로 전달됩니다hash
토스 포인트 결제 시 전달되는 데이터입니다.
- tidstring
  PG에서 발급한 결제 고유 식별 ID입니다. 문의 시 이 값을 사용하세요.