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
결제결과 수신 데이터
결제 결과는 기존에 resultUrl로 수신되는 결제 데이터와 같은 값을 전송하고 있습니다.
Webhook URL로 발송되는 결제결과 형식은 아래 Response Sample 형식입니다.
결제창에서 결제완료 후 반환되는 결제결과는 Depth가 없지만,
Webhook URL로 반환되는 결과는 Depth(info)가 있으니, 이 점 참고해주시기 바랍니다.
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
복사