
PG 웹훅은 결제가 끝나거나 취소됐을 때 결제 결과를 파트너 서버로 직접 보내 주는 알림입니다. 페이플 웹훅은 PCD_WEBHOOK_TYPE 값으로 지금 온 알림이 결제 완료인지 취소인지 알려 줍니다.
웹훅은 왜 필요한가요
결제창에서 결제가 끝나면 결과는 보통 고객의 브라우저를 거쳐 파트너 페이지로 돌아옵니다. 그런데 고객이 결제 직후 창을 닫거나 연결이 끊기면, 이 결과가 파트너 서버까지 오지 못할 수 있습니다. 고객은 결제를 마쳤는데 주문은 결제 대기로 남는 일이 생기는 것입니다.
웹훅은 이 빈틈을 막습니다. 페이플이 결제 결과를 브라우저와 따로 파트너 서버로 보내기 때문에, 결제창 쪽 결과를 놓쳐도 서버에서 결과를 받을 수 있습니다. 페이플 개발자센터도 웹훅을 이용하면 결제결과 누락을 방지할 수 있다고 안내합니다.
- 국내 카드/계좌 결제: 결제 완료, 취소 완료, 결제수단 등록, 결제수단 해지 알림을 받습니다.
- 해외 카드 결제: 결제 완료, 취소 완료 알림을 받습니다.
- 정산지급대행: 이체실행 결과(성공/실패)를 받습니다.
어떤 알림인지는 PCD_WEBHOOK_TYPE으로 나눕니다
국내 카드/계좌 결제 웹훅에는 PCD_WEBHOOK_TYPE 값이 함께 옵니다. 웹훅 주소 하나로 모든 알림을 받으면서, 이 값 하나로 무슨 일이 생겼는지 구분할 수 있습니다.
- PAYMENT: 결제 승인이 완료되면 보냅니다.
- REFUND: 결제가 취소되면 보냅니다. 파트너 관리자에서 직접 취소한 건도 포함됩니다.
- REGISTER: 정기결제 등에 쓸 카드나 계좌가 등록되면 보냅니다.
- TERMINATE: 카드나 계좌 등록을 해지하면 보냅니다.
REFUND에 파트너 관리자에서 직접 취소한 건도 들어간다는 점이 중요합니다. 운영 담당자가 관리자 화면에서 취소해도 서버가 알 수 있으니, 내 서비스의 주문 상태와 실제 결제 상태를 맞춰 둘 수 있습니다. 해외 카드 결제 웹훅은 국내와 받는 값의 형식이 다르니 해외 결제 문서를 기준으로 따로 구현합니다.
받은 웹훅은 이 순서로 처리합니다
웹훅을 받았다고 바로 주문 상태를 바꾸기보다, 아래 순서로 한 번 더 확인하는 편이 안전합니다.
- 알림 종류 나누기: PCD_WEBHOOK_TYPE이 PAYMENT인지 REFUND인지 먼저 봅니다.
- 주문 찾기: 웹훅에 담긴 주문번호 PCD_PAY_OID로 내 서비스의 주문을 찾습니다.
- 금액 확인: 결제 완료라면 웹훅의 결제 금액(PCD_PAY_TOTAL)이 내 서버에 저장해 둔 주문 금액과 같은지 확인합니다. 브라우저에서 넘어온 값이 아니라 서버에 있는 값과 비교해야 합니다.
- 상태 반영: 금액이 맞으면 주문을 결제 완료로 바꿉니다. 취소 완료라면 취소 금액(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영업일 안에 담당자가 연락드립니다.
의견을 남겨주세요