결제창 연동

국내 계좌결제〉비밀번호 간편결제

연동하기

반복 구매가 잦은 서비스에 이상적인 결제 방식입니다.
구매자가 페이플 결제창에서 계좌를 한 번 등록하면 이후부터는 비밀번호만으로 결제 요청이 가능합니다.

연동흐름

1. 결제창 호출

client

파라미터 확인 →

1.1 스크립트 태그

서버 환경에 따라 아래 스크립트를 태그해주세요.

Demo 스크립트

html

<script src="https://democpay.payple.kr/js/v1/payment.js?v=%datetime%"></script>

Live 스크립트

html

<script src="https://cpay.payple.kr/js/v1/payment.js?v=%datetime%"></script>

1.2 결제하기 버튼 이벤트

버튼 이벤트에는 파트너 인증을 위한 clientKey,
결제요청에 필요한 필수 파라미터들, 인증 결과를 수신하는 PCD_RST_URL, 그리고 결제창을 호출하는 PaypleCpayAuthCheck()가 포함됩니다.

1.3 클라이언트키 (clientKey)

라이브 환경에서는 계약이 완료된 후 페이플 담당자로부터 받은 클라이언트 키를
설정해주세요. 테스트 환경이라면, 아래 클라이언트키로 이용할 수 있습니다.

[DEMO] client key

text

1test_DF55F29DA654A8CBC0F0A9DD4B556486

1.4 승인 요청, 결제 방식

비밀번호 간편결제는 등록과 동시에 결제가 진행되므로 PCD_PAY_WORK, PCD_SIMPLE_FLAG, PCD_PAYER_AUTHTYPE 설정이 필요합니다.

1.5 결제창 호출

PaypleCpayAuthCheck(obj) 함수 호출 시 결제창이 띄워집니다.

payment.html

html

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?v=%datetime%"></script>
7  </head>
8  <body>
9    <!-- 주문서 내 결제하기 버튼 -->
10    <button id="btnPayment">결제하기</button>
11    <script>
12      // 결제 요청 파라메터
13      // 📄 https://docs.payple.kr/parameters/domestic-card/app#결제창호출
14      const params = {
15        clientKey: "test_DF55F29DA654A8CBC0F0A9DD4B556486",
16        PCD_PAY_TYPE: "transfer",
17        PCD_PAY_WORK: "CERT",
18        PCD_SIMPLE_FLAG: "Y",
19        PCD_PAYER_AUTHTYPE: "pwd",
20        PCD_RST_URL: "/result",
21      }
22
23      const handlePayment = (amount, goods_name) => {
24        window.PaypleCpayAuthCheck({
25          ...params,
26          PCD_PAY_TOTAL: amount,
27          PCD_PAY_GOODS: goods_name,
28        });
29      }
30
31      document.getElementById('btnPayment').addEventListener('click', function (event) {
32        handlePayment(1000, '테스트 상품');
33      });
34    </script>
35  </body>
36</html>

2. 인증결과 수신

server

파라미터 확인 →

결제 정보가 성공적으로 입력된 경우, 인증 결과는 POST 방식으로 PCD_RST_URL로 전송됩니다. 경로지정 방식에 따라 결제창이 다르게 띄워집니다.

· PC

경로	방식
상대경로	레이어팝업PC 권장 PC 환경에서 범용적으로 사용하는 방식입니다.
절대경로	다이렉트 보통 PC에서는 레이어팝업을 사용하기에 고객에게 생소할 수 있습니다.

경로

방식

상대경로

레이어팝업PC 권장

PC 환경에서 범용적으로 사용하는 방식입니다.

절대경로

다이렉트

보통 PC에서는 레이어팝업을 사용하기에 고객에게 생소할 수 있습니다.

· MO

경로	방식
상대경로	새탭(새창) 모바일 환경설정에 팝업차단 설정이 ON되어 있으면 창이 열리지않습니다. 카카오톡, 페이스북 등의 인앱 브라우저에서 결제가 발생하는 경우에는 다이렉트 방식을 사용 권장합니다.
절대경로	다이렉트MO권장 모바일 환경설정에 팝업차단 설정이 ON되어 있어도 결제 할 수 있습니다

경로

방식

상대경로

새탭(새창)

모바일 환경설정에 팝업차단 설정이 ON되어 있으면 창이 열리지않습니다.
카카오톡, 페이스북 등의 인앱 브라우저에서 결제가 발생하는 경우에는 다이렉트 방식을 사용 권장합니다.

절대경로

다이렉트MO권장

모바일 환경설정에 팝업차단 설정이 ON되어 있어도 결제 할 수 있습니다

SPA(Single Page Application)로 인증 결과를 수신하려면, 콜백 함수 파라미터를 추가해주세요.

·주의사항

callbackFunction을 사용할 경우, 함수 내부에 다음과 같은 요소들이 포함되면 XSS 공격으로 인식되어 요청이 차단될 수 있습니다.
아래와 같은 요소들을 제거하거나 사용하지 않는 형태로 코드를 작성한 후 시도해 주시기 바랍니다.
1. HTML 주석 태그 : <-- 주석내용 -->와 같은 주석은 XSS 공격으로 간주될 수 있습니다.
  callbackFunction을 사용할 때는 이러한 주석 태그를 제거해 주시기 바랍니다.
2. HTML 태그 : <div>, <span> 등의 일반적인 HTML 태그도 코드 내에 포함될 경우 XSS 공격으로 인식될 수 있으므로 주의가 필요합니다. 필요한 경우 순수 텍스트로 변환하거나 HTML 태그 사용을 자제해 주시기 바랍니다.
3. iframe 태그 : <iframe> 태그는 외부 콘텐츠를 삽입할 때 자주 사용되지만, XSS 공격에 악용될 수 있습니다.
  callbackFunction 내부에서 iframe 태그를 사용하지 않도록 해주시기 바랍니다.

웹훅(Webhook)이 등록되었으면 등록한 웹훅 URL로도 결과가 수신됩니다.

Server 인증 결과 수신

javascript

1export async function POST(request) {
2  const formData = await request.formData()
3
4  const PCD_PAY_RST = formData.get('PCD_PAY_RST')
5  const PCD_PAY_CODE = formData.get('PCD_PAY_CODE')
6  // ...
7
8  if (PCD_PAY_RST === 'success') {
9    // 인증 성공 → 결제 승인 요청 진행
10  } else {
11    // 인증 실패 처리
12  }
13
14  return Response.json({ isOk: true })
15}
16

Client 인증 결과 수신

javascript

1// 클라이언트에서 인증 결과를 수신할 경우에만 callbackFunction을 사용해주세요.
2// getResult는 파트너(상점)가 구현한 함수입니다.
3obj.callbackFunction = getResult;
4
5// getResult 함수 구현 예시
6function getResult(params) {
7    if (params.PCD_PAY_RESULT === 'success'){
8        // server side로 결제 승인요청 구현
9    } else {
10        // 결제 실패 페이지 렌더링
11    }
12}

3. API로 승인 요청

Server

파라미터 확인 →

3.1 PCD_CUST_KEY 확인

계약 완료 후 페이플 담당자에게 전달받은 PCD_CUST_KEY 를 확인해주세요.

·주의사항

PCD_CUST_KEY 외부에 노출되면 안되는 정보입니다. 보안에 유의해주세요.

3.2 승인 요청

REST API를 통한 승인 요청이 이루어지면, 해당 요청에 따라 실제 결제가 완료됩니다. 필히 원 주문 정보를 정확하게 확인해주세요.

3.3 요청 예시

Header 설정 후 API를 요청해주세요.

POSThttps://democpay.payple.kr/php/PayConfirmAct.php?ACT_=PAYM테스트 환경

POSThttps://cpay.payple.kr/php/PayConfirmAct.php?ACT_=PAYM라이브 환경

Header

1Content-Type: application/json
2Cache-Control: no-cache
3Referer: https://your-domain.com

Body

JSON

1{
2  "PCD_CST_ID": "test",
3  "PCD_CUST_KEY": "abcd1234567890",
4  "PCD_AUTH_KEY": "K0VnW…",
5  "PCD_PAY_REQKEY": "Vnx...",
6  "PCD_PAYER_ID": "OVA3…"
7}

·주의사항

Referer 필드에는 페이플에 등록된 파트너(상점)의 도메인을 정확히 입력해주세요. 도메인이 일치하지 않을 경우, ‘AUTH0004’ 오류 메시지가 반환됩니다.

4. 재결제 비밀번호 입력창 호출Client

Client

4.1 빌링키로 비밀번호 입력창 호출

인증 결과로 받은 빌링키를 스크립트에 추가함으로써, 구매자가 재결제할 때 비밀번호 입력창이 나타나도록 합니다. 스크립트의 나머지 데이터는 첫 결제 때와 동일하게 유지됩니다.

payment.html

HTML

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_WORK = "CERT"
16            obj.PCD_PAY_TYPE = "transfer";
17            obj.PCD_PAY_GOODS = "테스트 상품";
18            obj.PCD_PAY_TOTAL = 1000;
19			obj.PCD_SIMPLE_FLAG = "Y";
20			obj.PCD_PAYER_AUTHTYPE = "pwd";
21			obj.PCD_PAYER_ID = "OVA3…";
22            obj.PCD_RST_URL = "/result";
23            PaypleCpayAuthCheck(obj);
24        });
25    </script>
26  </body>
27</html>

5. 재결제 API로 승인 요청Server

Server

첫 결제 승인요청과 동일하게 진행됩니다.

6. 연동 완료

모든 연동 작업을 완료하셨습니다.
조회, 취소 기능이 필요하다면 운영 API 를 이용해주세요.