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
복사