결제창 연동
국내 카드결제〉간편페이 정기(빌링) 결제
연동하기
간편페이 정기(빌링) 결제는 구매자가 네이버페이 또는 카카오페이에서 카드를 인증해 빌링키를 발급받고, 해당 빌링키로 결제를 요청하는 방식입니다.
간편페이 빌링키는 첫 결제가 완료된 후 발급이 완료됩니다.
최초 결제 승인을 완료한 후 응답받은 PCD_PAYER_ID로 이후 결제를 요청할 수 있습니다.
연동 흐름
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)
라이브 환경에서는 계약 완료 후 발급받은 클라이언트키를 설정해주세요. 테스트 환경이라면 아래 클라이언트키를 사용할 수 있습니다.
1test_DF55F29DA654A8CBC0F0A9DD4B5564861.4 최초 빌링키 발급
최초 요청은 PCD_PAY_WORK=CERT, PCD_CARD_VER=01, PCD_EASYBILL_FLAG=Y로 설정합니다. AUTH 방식은 지원하지 않습니다.
1.5 간편페이 수단 선택
네이버페이는 PCD_PAY_METHOD=naverPay,
카카오페이는 PCD_PAY_METHOD=kakaoPay로 설정합니다.
두 수단 모두 등록된 카드만 지원하며 머니·포인트는 사용할 수 없습니다.
한 가지 수단만 계약된 파트너사는 이 값을 생략해도 계약된 수단만 결제창에 표시됩니다.
1.6 지원하지 않는 방식
간편페이 정기(빌링) 결제는 비밀번호 간편결제(pwd)와 함께 사용할 수 없습니다. 결제창에서 PCD_SIMPLE_FLAG=Y와 PCD_PAYER_AUTHTYPE=pwd를 함께 설정하면 PMCD0015가 반환됩니다.
1.7 결제창 호출
PaypleCpayAuthCheck(obj)를 호출하면 네이버페이 또는 카카오페이 카드 인증창이 표시됩니다.
2. 최초 인증 결과 수신
Server카드 인증이 완료되면 인증 결과가 POST 방식으로 PCD_RST_URL에 전달됩니다.
이 단계는 인증 결과이며 결제가 완료된 상태가 아닙니다.
응답받은 PCD_PAY_COFURL로 발급을 위한 결제 승인을 요청해주세요.
같은 카드라도 발급 요청에 따라 서로 다른 PCD_PAYER_ID가 발급될 수 있으므로,
카드번호가 아닌 PCD_PAYER_ID를 파트너사 회원 및 간편페이 수단과 함께 관리해주세요.
| 경로 | 방식 |
|---|---|
| 상대경로 | 레이어팝업 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 <button id="btnPayment">결제하기</button>
10 <script>
11 $('#btnPayment').on('click', function () {
12 let obj = {};
13 obj.clientKey = "test_DF55F29DA654A8CBC0F0A9DD4B556486";
14 obj.PCD_PAY_TYPE = "card";
15 obj.PCD_PAY_WORK = "CERT";
16 obj.PCD_CARD_VER = "01";
17 obj.PCD_EASYBILL_FLAG = "Y";
18 obj.PCD_PAY_METHOD = "naverPay";
19 obj.PCD_PAY_GOODS = "테스트 상품";
20 obj.PCD_PAY_TOTAL = 1000;
21 obj.PCD_RST_URL = "/result";
22 PaypleCpayAuthCheck(obj);
23 });
24 </script>
25 </body>
26</html>
273. 발급을 위한 결제 승인 요청
Server3.1 PCD_CUST_KEY 확인
계약 완료 후 페이플 담당자에게 전달받은 PCD_CUST_KEY를 확인해주세요.
·주의사항
PCD_CUST_KEY는 외부에 노출되면 안 되는 정보입니다. 보안에 유의해주세요.
3.2 승인 요청
빌링키 인증 결과로 받은 인증값을 이용해 최초 결제를 승인합니다. 이 요청이 성공하면 간편페이 빌링키 발급이 완료됩니다.
3.3 요청 예시
Header 설정 후 API를 요청해주세요.
아래는 API 요청 주소 예시입니다. 실제 API 요청 주소는 빌링키 인증 결과의 PCD_PAY_COFURL로 요청해주세요.
1Content-Type: application/json
2Cache-Control: no-cache
3Referer: https://your-domain.com1{
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. 결제를 위한 파트너 인증 요청
Server4.1 PCD_CUST_KEY 확인
계약 완료 후 페이플 담당자에게 전달받은 PCD_CUST_KEY를 확인해주세요.
·주의사항
PCD_CUST_KEY는 외부에 노출되면 안 되는 정보입니다. 보안에 유의해주세요.
4.2 인증 요청
빌링키 결제 전에 파트너 인증을 요청합니다. 응답받은 인증값은 승인 요청에 사용합니다.
4.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’ 오류 메시지가 반환됩니다.
5. 빌링키로 재결제
Server5.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_PAY_METHOD": "naverPay",
7 "PCD_PAYER_ID": "OVA3...",
8 "PCD_PAY_GOODS": "테스트 상품",
9 "PCD_PAY_TOTAL": "1000",
10 "PCD_SIMPLE_FLAG": "Y"
11}·주의사항
PCD_PAY_METHOD를 전송하는 경우 PCD_PAYER_ID 발급 시 선택한 간편페이 수단과 동일하게 설정해주세요.