결제창 연동
국내 카드결제〉정기(빌링) 결제
연동하기
정기(빌링)결제는 구독 서비스를 위한 결제방식입니다.
구매자가 페이플 결제창에서 카드를 한 번 등록하면 이후부터는 별도 인증없이 결제 요청이 가능합니다.
연동 흐름
1. 결제창 호출
Client1.1 스크립트 태그
서버 환경에 따라 아래 스크립트를 태그해주세요.
1<!-- 테스트 -->
2<script src="https://democpay.payple.kr/js/v1/payment.js"></script>1<!-- 라이브 -->
2<script src="https://cpay.payple.kr/js/v1/payment.js"></script>1.2 결제하기 버튼 이벤트
버튼 이벤트에는 파트너 인증을 위한 clientKey, 결제요청에
필요한 필수 파라미터들, 인증 결과를 수신하는 PCD_RST_URL,
그리고 결제창을 호출하는 PaypleCpayAuthCheck()가 포함됩니다.
1.3 클라이언트키 (clientKey)
라이브 환경에서는 계약이 완료된 후 페이플 담당자로부터 받은 클라이언트 키를
설정해주세요. 테스트 환경이라면, 아래 클라이언트키로 이용할 수 있습니다.
test_DF55F29DA654A8CBC0F0A9DD4B5564861.4 승인 요청 방식
카드 등록만 필요하다면 AUTH ,
등록과 동시에 결제가 필요하다면 CERT 로 설정합니다.
1.5 결제방식
정기(빌링)결제는 PCD_CARD_VER 을 “01” 로 설정합니다.
1.6 결제창 호출
PaypleCpayAuthCheck(obj) 함수 호출 시 결제창이 띄워집니다.
2. 인증결과 수신
Server결제 정보가 성공적으로 입력된 경우, 인증 결과는 POST 방식으로
PCD_RST_URL로 전송됩니다. 경로지정 방식에 따라 결제창이 다르게 띄워집니다.
| 경로 | 방식 |
|---|---|
| 상대경로 | 레이어팝업PC 권장 PC 환경에서 범용적으로 사용하는 방식입니다. |
| 절대경로 | 다이렉트 보통 PC에서는 레이어팝업을 사용하기에 고객에게 생소할 수 있습니다. |
| 경로 | 방식 |
|---|---|
| 상대경로 | 새탭(새창)
|
| 절대경로 | 다이렉트MO권장 모바일 환경설정에 팝업차단 설정이 ON되어 있어도 결제 할 수 있습니다 |
SPA(Single Page Application)로 인증 결과를 수신하려면, 콜백 함수
파라미터를 추가해주세요.
1<!-- getResult는 파트너(상점)가 구현한 함수입니다. -->
2obj.callbackFunction = getResult;
3
4<!-- getResult 함수 구현 예시 -->
5function getResult(params) {
6 if (params.PCD_PAY_RESULT === 'success'){
7 <!-- server side로 결제 승인요청 구현 -->
8 }
9 else {
10 <!-- 결제 실패 페이지 렌더링 -->
11 }
12}·주의사항
- callbackFunction을 사용할 경우, 함수 내부에 다음과 같은 요소들이 포함되면 XSS 공격으로 인식되어 요청이 차단될 수 있습니다.
- 아래와 같은 요소들을 제거하거나 사용하지 않는 형태로 코드를 작성한 후 시도해 주시기 바랍니다.
- HTML 주석 태그 : <-- 주석내용 -->와 같은 주석은 XSS 공격으로 간주될 수 있습니다.
callbackFunction을 사용할 때는 이러한 주석 태그를 제거해 주시기 바랍니다. - HTML 태그 : <div>, <span> 등의 일반적인 HTML 태그도 코드 내에 포함될 경우 XSS 공격으로
인식될 수 있으므로 주의가 필요합니다.
필요한 경우 순수 텍스트로 변환하거나 HTML 태그 사용을 자제해 주시기 바랍니다. - iframe 태그 : <iframe> 태그는 외부 콘텐츠를 삽입할 때 자주 사용되지만, XSS 공격에 악용될 수 있습니다.
callbackFunction 내부에서 iframe 태그를 사용하지 않도록 해주시기 바랍니다.
- HTML 주석 태그 : <-- 주석내용 -->와 같은 주석은 XSS 공격으로 간주될 수 있습니다.
웹훅(Webhook)이 등록되었으면 등록한 웹훅 URL로도 결과가 수신됩니다.
1<!DOCTYPE html>
2<html>
3 <head>
4 <meta charset="UTF-8">
5 <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>
6 <script src="https://democpay.payple.kr/js/v1/payment.js"></script>
7 </head>
8 <body>
9 <!-- 주문서 내 결제하기 버튼 -->
10 <button id="btnPayment">결제하기</button>
11 <script>
12 $('#btnPayment').on('click', function (event) {
13 let obj = {};
14 obj.clientKey = "test_DF55F29DA654A8CBC0F0A9DD4B556486";
15 obj.PCD_PAY_TYPE = "card";
16 obj.PCD_PAY_WORK = "AUTH"
17 obj.PCD_CARD_VER = "01";
18 obj.PCD_PAY_GOODS = "테스트 상품";
19 obj.PCD_PAY_TOTAL = 1000;
20 obj.PCD_RST_URL = "/result";
21 PaypleCpayAuthCheck(obj);
22 });
23 </script>
24 </body>
25</html>3. 결제를 위한 파트너 인증 요청
Server3.1 PCD_CUST_KEY 확인
계약 완료 후 페이플 담당자에게 전달받은 PCD_CUST_KEY를 확인해주세요.
·주의사항
PCD_CUST_KEY 외부에 노출되면 안되는 정보입니다. 보안에 유의해주세요.
3.2 인증 요청
REST API를 통한 승인 요청이 이루어지면, 해당 요청에 따라 실제 결제가 완료됩니다. 필히 원 주문 정보를 정확하게 확인해주세요.
3.3 요청 예시
Header 설정 후 API를 요청해주세요.
1Content-Type: application/json
2Cache-Control: no-cache
3Referer: https://your-domain.com1{
2 "cst_id": "test",
3 "custKey": "abcd1234567890",
4 "PCD_PAY_TYPE": "card",
5 "PCD_SIMPLE_FLAG": "Y"
6}·주의사항
Referer 필드에는 페이플에 등록된 파트너(상점)의 도메인을 정확히 입력해주세요. 도메인이 일치하지 않을 경우, ‘AUTH0004’ 오류 메시지가 반환됩니다.
4. 빌링키로 승인 요청
Server4.1 승인 요청
파트너 인증 후 REST API를 활용하여 빌링키를 통한 승인 요청이 이루어지면, 이에 따른 실결제가 완료됩니다.
1Content-Type: application/json
2Cache-Control: no-cache
3Referer: https://your-domain.com1{
2 "PCD_CST_ID": "UFVNNVZ...",
3 "PCD_CUST_KEY": "T3JzRkp5L...",
4 "PCD_AUTH_KEY": "a688ccb3555...",
5 "PCD_PAY_TYPE": "card",
6 "PCD_PAYER_ID": "OVA3...",
7 "PCD_PAY_GOODS": "테스트 상품",
8 "PCD_PAY_TOTAL": "1000",
9 "PCD_SIMPLE_FLAG": "Y"
10}·주의사항
Referer 필드에는 페이플에 등록된 파트너(상점)의 도메인을 정확히 입력해주세요. 도메인이 일치하지 않을 경우, ‘AUTH0004’ 오류 메시지가 반환됩니다.