1. 정의
파트너로부터 들어온 결제요청을 처리하는 경우, 간혹 카드사로부터 결제결과에 대한 리턴값이 오지 않거나, 지연되는 현상이 발생할 수 있습니다.
이를 예방하기 위해서 페이플에서 Webhook URL을 지원합니다.
웹훅(Webhook)이란,
한 응용 프로그램에서 어떤 이벤트가 발생했을 때 다른 응용 프로그램으로 실시간 정보를 제공하는 방법입니다.
•
파트너에서 요청 결과 수신용 웹 페이지(URL)을 설정하면
페이플에서 결제결과와 결제취소 결과를 해당 URL로 전송합니다.
포트 443만 사용 가능합니다. (HTTPS 프로토콜 필수)
2. 발송시점
•
Webhook URL로는 결제결과와 결제 취소결과가 발송됩니다.
Webhook URL을 설정한 경우,
결제 데이터는 기존에 resultUrl로 수신되는 결제 데이터와 같은 값을 전송하고 있습니다.
•
Webhook URL 등록 없이 결제 결과를 처리하려면 resultUrl로 수신한 결제 결과(Response)로 처리하면 되지만, 페이플에서는 결과 수신 누락을 방지하기 위해 Webhook URL 등록을 권장합니다.
•
테스트 서버에서는 별도의 계정을 발급받아야 Webhook URL 테스트가 가능합니다.
◦
별도의 계정을 발급받지 않는 경우, Webhook URL 테스트가 불가합니다.
◦
테스트 서버에서 Webhook URL 테스트가 필요하다면, 페이플 고객센터(help@payple.kr)로 연락주시면 파트너 전용 테스트 계정을 발급해드립니다.
3. Webhook URL 등록/수정
•
페이플 해외결제 파트너 관리자 > 기본정보 - 결제결과 수신 URL
> 기본정보 - 결제결과 수신 URL◦
결제 결과 수신 URL (가맹점 미수신 결과 확인) 입력
◦
결제 취소 결과 수신 URL 입력
◦
URL 예시: https://www.test.com/webhook
Webhook URL을 유효한 URL로 설정해주세요.
•
HTTPS URL이여야 합니다.
•
HEAD 및 POST 요청에 모두 HTTP 상태 코드 200으로 응답해야합니다.
•
10초 이내에 POST 요청에 응답해야합니다.
•
신뢰할 수 있는 출처에서 발급한 인증서를 사용해야합니다.
4. 전송 규약
•
JSON 방식으로 데이터를 POST
5. White IP 등록
파트너사에서 방화벽 정책을 설정하셨을 경우, 페이플의 White IP 등록이 필요합니다.
6. Data Sample
각 파라미터의 자세한 설명은 파라미터(Parameter) 정의에서 확인해보세요!
에서 확인해보세요!결제결과 수신 데이터
결제 결과는 기존에 resultUrl로 수신되는 결제 데이터와 같은 값을 전송하고 있습니다.
Response sample
수신 데이터 예시로 보기
{
"type": "요청 종류",
"result": "응답 코드",
"message": "응답 메시지",
"resultUrl": "결제결과 반환(Return) URL",
"api_id": "결제 요청 고유키",
"api_date": "결제 시간(GMT +9)",
"info": {
"service_oid": "주문번호",
"comments": "상품명",
"pay_type": "결제수단",
"billing_key": "빌링키(카드 정보를 암호화 한 값)",
"totalAmount": "결제 요청금액",
"currency": "통화",
"firstName": "카드소유주 이름",
"lastName": "카드소유주 성",
"email": "이메일 주소",
"phoneNumber": "휴대전화 번호",
"card_number": "카드번호 (일부 마스킹 처리)",
"submitTimeUtc": "결제 시간(GMT)"
},
"serviceDefine": "사용자 정의 파라미터"
}
JSON
취소결과 수신 데이터
취소 요청을 한 파트너사 서버로 수신되는 취소 데이터와 같은 값을 전송하고 있습니다.
Response sample
수신 데이터 예시로 보기
{
"type": "요청 종류",
"result": "응답 코드",
"message": "응답 메시지",
"resultUrl": "취소 요청시 보낸 값 그대로 반환되는 URL",
"api_id": "결제취소 고유키",
"api_date": "결제취소 요청 일자",
"info": {
"totalAmount": "결제취소 요청 금액",
"currency": "결제취소 통화",
"service_oid": "원거래 결제건 주문번호",
"submitTimeUtc": "결제 취소시간(GMT)"
},
"serviceDefine": "사용자 정의 파라미터"
}
JSON