뉴스레터_With Payple

PG 웹훅으로 결제 완료와 취소 알림을 놓치지 않는 법

PG 웹훅은 결제가 끝나거나 취소됐을 때 결과를 파트너 서버로 직접 보내 줍니다. 페이플 웹훅의 PCD_WEBHOOK_TYPE 값으로 알림을 나누고, 주문번호와 금액을 확인해 반영하는 순서를 정리했습니다.

| 조회 0 |
0
|
from.
페이플
첨부 이미지

PG 웹훅은 결제가 끝나거나 취소됐을 때 결제 결과를 파트너 서버로 직접 보내 주는 알림입니다. 페이플 웹훅은 PCD_WEBHOOK_TYPE 값으로 지금 온 알림이 결제 완료인지 취소인지 알려 줍니다.

 

웹훅은 왜 필요한가요

결제창에서 결제가 끝나면 결과는 보통 고객의 브라우저를 거쳐 파트너 페이지로 돌아옵니다. 그런데 고객이 결제 직후 창을 닫거나 연결이 끊기면, 이 결과가 파트너 서버까지 오지 못할 수 있습니다. 고객은 결제를 마쳤는데 주문은 결제 대기로 남는 일이 생기는 것입니다.

첨부 이미지

웹훅은 이 빈틈을 막습니다. 페이플이 결제 결과를 브라우저와 따로 파트너 서버로 보내기 때문에, 결제창 쪽 결과를 놓쳐도 서버에서 결과를 받을 수 있습니다. 페이플 개발자센터도 웹훅을 이용하면 결제결과 누락을 방지할 수 있다고 안내합니다.

  • 국내 카드/계좌 결제: 결제 완료, 취소 완료, 결제수단 등록, 결제수단 해지 알림을 받습니다.
  • 해외 카드 결제: 결제 완료, 취소 완료 알림을 받습니다.
  • 정산지급대행: 이체실행 결과(성공/실패)를 받습니다.

 

어떤 알림인지는 PCD_WEBHOOK_TYPE으로 나눕니다

국내 카드/계좌 결제 웹훅에는 PCD_WEBHOOK_TYPE 값이 함께 옵니다. 웹훅 주소 하나로 모든 알림을 받으면서, 이 값 하나로 무슨 일이 생겼는지 구분할 수 있습니다.

첨부 이미지
  • PAYMENT: 결제 승인이 완료되면 보냅니다.
  • REFUND: 결제가 취소되면 보냅니다. 파트너 관리자에서 직접 취소한 건도 포함됩니다.
  • REGISTER: 정기결제 등에 쓸 카드나 계좌가 등록되면 보냅니다.
  • TERMINATE: 카드나 계좌 등록을 해지하면 보냅니다.

REFUND에 파트너 관리자에서 직접 취소한 건도 들어간다는 점이 중요합니다. 운영 담당자가 관리자 화면에서 취소해도 서버가 알 수 있으니, 내 서비스의 주문 상태와 실제 결제 상태를 맞춰 둘 수 있습니다. 해외 카드 결제 웹훅은 국내와 받는 값의 형식이 다르니 해외 결제 문서를 기준으로 따로 구현합니다.

 

받은 웹훅은 이 순서로 처리합니다

웹훅을 받았다고 바로 주문 상태를 바꾸기보다, 아래 순서로 한 번 더 확인하는 편이 안전합니다.

첨부 이미지
  1. 알림 종류 나누기: PCD_WEBHOOK_TYPE이 PAYMENT인지 REFUND인지 먼저 봅니다.
  2. 주문 찾기: 웹훅에 담긴 주문번호 PCD_PAY_OID로 내 서비스의 주문을 찾습니다.
  3. 금액 확인: 결제 완료라면 웹훅의 결제 금액(PCD_PAY_TOTAL)이 내 서버에 저장해 둔 주문 금액과 같은지 확인합니다. 브라우저에서 넘어온 값이 아니라 서버에 있는 값과 비교해야 합니다.
  4. 상태 반영: 금액이 맞으면 주문을 결제 완료로 바꿉니다. 취소 완료라면 취소 금액(PCD_REFUND_TOTAL)을 확인하고 주문을 취소 상태로 바꿉니다.

같은 주문의 웹훅이 결제창 결과와 함께 두 번 들어올 수도 있으니, 이미 반영한 주문이면 다시 처리하지 않게 만들어 둡니다. 정기결제를 쓴다면 문서 안내대로 PCD_PAY_YEAR, PCD_PAY_MONTH 값을 추가해 중복결제를 막을 수 있습니다.

 

자주 묻는 질문

Q. 테스트 환경에서도 웹훅을 받을 수 있나요?

네. 다만 테스트는 페이플 고객센터를 통해 테스트 계정을 발급받은 뒤 이용할 수 있습니다.

Q. 결제 완료 웹훅에는 어떤 값이 오나요?

결제 결과(PCD_PAY_RST), 결과 코드(PCD_PAY_CODE), 결제수단(PCD_PAY_TYPE), 주문번호(PCD_PAY_OID), 상품명, 결제 금액 등이 옵니다. 카드 결제라면 매출전표 주소(PCD_PAY_CARDRECEIPT)도 함께 옵니다. 전체 목록은 개발자센터 웹훅 문서에 있습니다.

Q. 웹훅 주소는 어디에서 등록하나요?

라이브 환경에서는 파트너 관리자 › 기본정보에서 등록합니다. 정산지급대행 웹훅은 파트너 관리자 › 정산지급대행 › 정산지급대행 이용정보에서 등록합니다.

Q. 클로드 같은 AI에게 웹훅 코드를 맡겨도 되나요?

페이플 MCP를 연결하면 AI가 개발자센터 문서 원문을 읽고 코드를 씁니다. 그래도 금액 확인과 중복 처리 방지는 직접 한 번 더 살펴보세요.

 

시작하기

카드결제가 필요하시면 페이플 PG 가입 문의에서 3분이면 신청할 수 있습니다. 1영업일 안에 담당자가 연락드립니다.

 

함께 보면 좋은 글

원문 보기

 

다가올 뉴스레터가 궁금하신가요?

지금 구독해서 새로운 레터를 받아보세요

✉️

이번 뉴스레터 어떠셨나요?

With Payple 님에게 ☕️ 커피와 ✉️ 쪽지를 보내보세요!

댓글

의견을 남겨주세요

확인
의견이 있으신가요? 제일 먼저 댓글을 달아보세요 !

다른 뉴스레터

With Payple과 대화하기
© 2026 With Payple

페이플의 파트너와 구독자에게 도움되는 소식을 보내 드립니다.

뉴스레터 문의mkt@payple.kr

메일리 로고

도움말 오류 및 기능 관련 제보

서비스 이용 문의admin@team.maily.so 채팅으로 문의하기

메일리 사업자 정보

메일리 (대표자: 이한결) | 대표번호: 070-8027-1409 | 사업자번호: 717-47-00705 | 서울특별시 송파구 위례광장로 199, 5층 501-2-31호

이용약관 | 개인정보처리방침 | 정기결제 이용약관 | 라이선스