Search

Webhook URL

1. 정의

파트너로부터 들어온 결제요청을 처리하는 경우, 간혹 카드사나 은행으로부터 결제결과에 대한 리턴값이 오지 않거나, 지연되는 현상이 발생할 수 있습니다.
이를 예방하기 위해서 페이플에서 Webhook URL을 지원합니다.
웹훅(Webhook)이란, 한 응용 프로그램에서 어떤 이벤트가 발생했을 때 다른 응용 프로그램으로 실시간 정보를 제공하는 방법입니다.
파트너에서 요청결과 수신용 웹페이지(URL)을 설정하게 되면 페이플에서 각종 이벤트가 발생할때마다 해당 URL로 데이터를 전송하게 됩니다.
결제결과 수신 뿐만 아니라 등록된 계좌나 카드(빌링키)가 해지될 때도 웹훅 URL로 수신할 수 있습니다.
페이플 파트너 관리자를 통해 개별적으로 계좌나 카드의 등록을 해지하는 경우 웹훅으로도 내역을 확인할 수 있는 장점이 있습니다.
포트 80(8080), 443만 사용 가능합니다. (HTTPS 프로토콜 필수)

2. 프로세스 개요

3. 발송시점

Webhook URL은 다음의 시점에 발송됩니다.

3-1. 결제결과 수신

결제 시
취소 시 (파트너 관리자에서 취소 포함)
결제 수신이 지연된 거래건 수신 시
결제수단(카드/계좌) 등록 이벤트 발생시

3-2. 결제수단(카드/계좌) 해지결과 수신

페이플 파트너 관리자에서 직접 등록 해지시 해지결과를 수신할 수 있습니다.
‘등록계좌 해지’ API를 통해 해지한 건은 웹훅URL로 수신되지 않습니다.
Webhook URL을 설정한 경우, 결제데이터의 수신은 기존에 PCD_RST_URL로 수신되는 결제데이터와 중복되어 받게 됩니다. 미수신되는 케이스를 줄이기 위해 웹훅을 사용하므로, 결제데이터 처리의 기준은 웹훅 수신 데이터를 기준으로 삼습니다. - 페이플에서는 결과 수신실패 누락을 방지하기 위해 Webhook URL 등록을 권장합니다. - 테스트 서버에서는 별도의 계정을 발급받지 않는 한 Webhook URL 등록 및 테스트가 불가합니다. - 테스트 서버에서 Webhook URL을 테스트하기 위해서 help@payple.kr 로 연락주시면 파트너 전용 테스트 계정을 발급하여 드립니다. - Webhook URL 등록 없이 테스트하시려면 PCD_RST_URL 로 수신받은 Response 데이터 로 결과를 처리합니다.

4. Webhook URL 설정방법

페이플 파트너 관리자 > 기본정보 > 결제 결과 수신 URL (가맹점 미수신 결과 확인) 입력
페이플 파트너 관리자 > 기본정보 > 계좌(카드)해지결과 수식 URL 입력

5. 전송 규약

JSON 방식으로 데이터를 POST

6. White IP 등록

파트너사에서 방화벽 정책을 설정하셨을 경우, 페이플의 White IP 등록이 필요합니다.
White IP 리스트는 페이플로 문의(dev@payple.kr)해주시기 바랍니다.

7. Data Sample

각 파라미터의 자세한 설명은 파라미터(Parameter) 정의에서 확인해보세요!

결제결과 수신 데이터

카드 결제결과 수신 데이터
Response sample
수신 데이터 예시로 보기
{ "PCD_PAY_RST" : "결제결과" "PCD_PAY_CODE" : "결제결과 리턴 코드" "PCD_PAY_MSG" : "결제결과 리턴 메시지" "PCD_PAY_TYPE" : "결제수단 (card)" "PCD_CARD_VER" : "카드 세부 결제방식" "PCD_PAY_WORK" : "결제방식" "PCD_AUTH_KEY" : "파트너 인증 토큰 값" "PCD_PAY_REQKEY" : "(CERT방식) 최종 결제요청 승인키" "PCD_PAY_HOST" : "파트너 인증 후 본 요청시 필요한 페이플 도메인 주소" "PCD_PAY_URL" : "파트너 인증 후 본 요청시 필요한 페이플 도메인 주소" "PCD_PAY_COFURL" : "(CERT방식) 최종 결제요청 URL" "PCD_PAYER_ID" : "카드(계좌)등록 후 리턴받은 빌링키" "PCD_PAYER_NO" : "회원번호" "PCD_PAYER_NAME" : "결제고객의 이름" "PCD_PAYER_HP" : "결제고객의 휴대전화번호" "PCD_PAYER_EMAIL" : "결제고객의 이메일주소" "PCD_PAY_YEAR" : "월 중복결제 년" "PCD_PAY_MONTH" : "월 중복결제 월" "PCD_PAY_OID" : "주문번호" "PCD_PAY_GOODS" : "상품명" "PCD_PAY_AMOUNT" : "결제 요청금액" "PCD_PAY_DISCOUNT" : "페이플 이벤트 할인금액" "PCD_PAY_AMOUNT_REAL" : "실 결제금액" "PCD_PAY_TOTAL" : "결제금액의 총합계" "PCD_PAY_TAXTOTAL" : "과세금액" "PCD_PAY_ISTAX" : "과세여부" "PCD_PAY_CARDNAME" : "카드사" "PCD_PAY_CARDNUM" : "카드번호" "PCD_PAY_CARDQUOTA" : "카드 할부 개월 수" "PCD_PAY_CARDTRADENUM" : "카드승인 거래 키" "PCD_PAY_CARDAUTHNO" : "카드거래 승인번호" "PCD_PAY_CARDRECEIPT" : "신용카드 매출전표 URL" "PCD_PAY_TIME" : "결제완료 시간" "PCD_REGULER_FLAG" : "월 중복결제 방지 사용여부" "PCD_SIMPLE_FLAG" : "페이플 간편결제 방식 선택여부" "PCD_RST_URL" : "결제(요청)결과 RETURN URL / 결제창 호출방식" "PCD_LINK_ADD_PARAM": "링크결제 생성시 추가로 지정한 사용자 정의 파라미터" }
JSON
복사
계좌 결제결과 수신 데이터
Response sample
수신 데이터 예시로 보기
{ "PCD_PAY_RST" : "결제결과" "PCD_PAY_CODE" : "결제결과 리턴 코드" "PCD_PAY_MSG" : "결제결과 리턴 메시지" "PCD_PAY_TYPE" : "결제수단 (transfer)" "PCD_PAY_WORK" : "결제방식" "PCD_AUTH_KEY" : "파트너 인증 토큰 값" "PCD_PAY_REQKEY" : "(CERT방식) 최종 결제요청 승인키" "PCD_PAY_HOST" : "파트너 인증 후 본 요청시 필요한 페이플 도메인 주소" "PCD_PAY_URL" : "파트너 인증 후 본 요청시 필요한 페이플 도메인 주소" "PCD_PAY_COFURL" : "(CERT방식) 최종 결제요청 URL" "PCD_PAYER_ID" : "계좌(카드)등록 후 리턴받은 빌링키" "PCD_PAYER_NO" : "회원번호" "PCD_PAYER_NAME" : "결제고객의 이름" "PCD_PAYER_HP" : "결제고객의 휴대전화번호" "PCD_PAYER_EMAIL" : "결제고객의 이메일주소" "PCD_PAY_BANKACCTYPE" : "고객 종류 (personal | corporate)" "PCD_PAY_YEAR" : "월 중복결제 년" "PCD_PAY_MONTH" : "월 중복결제 월" "PCD_PAY_OID" : "주문번호" "PCD_PAY_GOODS" : "상품명" "PCD_PAY_AMOUNT" : "결제 요청금액" "PCD_PAY_DISCOUNT" : "페이플 이벤트 할인금액" "PCD_PAY_AMOUNT_REAL" : "실 결제금액" "PCD_PAY_TOTAL" : "결제금액의 총합계" "PCD_PAY_TAXTOTAL" : "과세금액" "PCD_PAY_BANK" : "결제 계좌 은행 코드번호" "PCD_PAY_BANKNAME" : "결제 계좌 은행명" "PCD_PAY_BANKNUM" : "계좌번호" "PCD_PAY_ISTAX" : "과세여부" "PCD_PAY_TIME" : "결제완료 시간" "PCD_REGULER_FLAG" : "월 중복결제 방지 사용여부" "PCD_TAXSAVE_FLAG" : "현금영수증 발행창 사용여부" "PCD_TAXSAVE_RST" : "현금영수증 발행결과" "PCD_TAXSAVE_MGTNUM" : "현금영수증 발행된 국세청 발행번호" "PCD_SIMPLE_FLAG" : "페이플 간편결제 방식 선택여부" "PCD_RST_URL" : "결제(요청)결과 RETURN URL / 결제창 호출방식" "PCD_LINK_ADD_PARAM": "링크결제 생성시 추가로 지정한 사용자 정의 파라미터" }
JSON
복사
결제취소 수신 데이터
Response sample
수신 데이터 예시로 보기
{ "PCD_PAY_RST" : "결제취소결과", "PCD_PAY_CODE" : "결제취소결과 리턴 코드", "PCD_PAY_MSG" : "결제취소결과 리턴 메시지", "PCD_PAY_OID" : "주문번호", "PCD_PAY_TYPE" : "결제수단 (transfer | card)", "PCD_PAYER_ID" : "계좌(카드) 등록시 리턴받은 빌링키", "PCD_PAY_GOODS" : "상품명", "PCD_REFUND_TOTAL" : "취소 요청금액", "PCD_REFUND_TAXTOTAL" : "취소요청금액의 지정 부가세", "PCD_PAY_CARDTRADENUM" : "카드 승인취소 거래 키", "PCD_PAY_CARDRECEIPT" : "매출전표 출력 링크" }
JSON
복사

카드/계좌 등록 수신 데이터

카드 등록 수신 데이터
Response sample
수신 데이터 예시로 보기
{ "PCD_PAY_RST": "등록결과" "PCD_PAY_CODE": "등록결과 리턴 코드" "PCD_PAY_MSG": "등록결과 리턴 메시지" "PCD_PAY_WORK": "결제방식 (등록: AUTH)" "PCD_AUTH_KEY": "파트너 인증 토큰 값" "PCD_PAY_TYPE": "등록한 결제수단 (card)" "PCD_PAYER_AUTHTYPE": "비밀번호 결제 인증방식" "PCD_PAYER_NO": "회원번호" "PCD_PAYER_ID": "카드 등록 후 리턴받은 빌링키" "PCD_PAYER_NAME": "고객의 이름" "PCD_PAYER_HP": "고객의 휴대전화번호" "PCD_PAY_CARDNAME": "카드사" "PCD_PAY_CARDNUM": "카드번호" "PCD_RST_URL": "결제(요청)결과 RETURN URL / 결제창 호출방식" }
JSON
복사
계좌 등록 수신 데이터
Response sample
수신 데이터 예시로 보기
{ "PCD_PAY_RST": "등록결과" "PCD_PAY_CODE": "등록결과 리턴 코드" "PCD_PAY_MSG": "등록결과 리턴 메시지" "PCD_PAY_WORK": "결제방식 (등록: AUTH)" "PCD_AUTH_KEY": "파트너 인증 토큰 값" "PCD_PAY_TYPE": "등록한 결제수단 (transfer)" "PCD_PAYER_NO": "회원번호" "PCD_PAYER_ID": "계좌 등록 후 리턴받은 빌링키" "PCD_PAYER_NAME": "고객의 이름" "PCD_PAYER_HP": "고객의 휴대전화번호" "PCD_RST_URL": "결제(요청)결과 RETURN URL / 결제창 호출방식" "PCD_PAY_BANKACCTYPE": "고객 종류 (personal | corporate)" "PCD_PAY_BANK" : "결제 계좌 은행 코드번호" "PCD_PAY_BANKNAME" : "결제 계좌 은행명" "PCD_PAY_BANKNUM" : "계좌번호" }
JSON
복사

카드/계좌 해지 수신 데이터

카드 해지 수신 데이터
Response sample
수신 데이터 예시로 보기
{ "PCD_PAY_RST": "해지결과" "PCD_PAY_CODE": "해지결과 리턴 코드" "PCD_PAY_MSG" : "해지결과 메시지" "PCD_PAY_WORK": "API 요청 종류 (해지 : PUSERDEL)" "PCD_PAY_TYPE": "해지한 결제수단 (card)" "PCD_PAYER_ID": "카드 등록 후 리턴받은 빌링키" "PCD_PAYER_NO" : "회원번호" }
JSON
복사
계좌 해지 수신 데이터
Response sample
수신 데이터 예시로 보기
{ "PCD_PAY_RST": "해지결과" "PCD_PAY_CODE": "해지결과 리턴 코드" "PCD_PAY_MSG" : "해지결과 메시지" "PCD_PAY_WORK": "API 요청 종류 (해지 : PUSERDEL)" "PCD_PAY_TYPE": "해지한 결제수단 (transfer)" "PCD_PAYER_ID": "계좌 등록 후 리턴받은 빌링키" "PCD_PAYER_NO" : "회원번호" }
JSON
복사