국내 간편페이 정기(빌링) 결제
V1구버전 개발자센터
V2신버전 개발자센터

국내 간편페이 정기(빌링) 결제

간편페이 정기(빌링) 결제는 구매자가 네이버페이 또는 카카오페이에서 카드를 인증해 빌링키를 발급받고, 해당 빌링키로 결제를 요청하는 방식입니다.
간편페이 빌링키는 첫 결제가 완료된 후 발급이 완료됩니다.
최초 결제 승인을 완료한 후 응답받은 PCD_PAYER_ID로 이후 결제를 요청할 수 있습니다.

00연동 준비

페이플이 제공하는 테스트 정보를 통해 계약 전 단계에서도 누구나 연동 체험이 가능합니다.

스크립트 정보
사전 로드 (jQuery)<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>
테스트용<script src="https://democpay.payple.kr/js/v1/payment.js"></script>
라이브용<script src="https://cpay.payple.kr/js/v1/payment.js"></script>
테스트 환경 접속 정보
접속 도메인https://democpay.payple.kr
cst_idtest
custKeyabcd1234567890
clientKeytest_DF55F29DA654A8CBC0F0A9DD4B556486
PCD_REFUND_KEY (결제취소 시 이용)a41ce010ede9fcbfb3be86b24858806596a9db68b79d138b147c3e563e1829a0
clientKey (체험하기 전용)test_FD3876EF0522D8D6B7D9B783F858DC5A
주의
요청 header 설정파트너 인증시 referer 헤더의 값을 결제창이 호출될 도메인으로 입력해주세요. 별도의 테스트 계정을 발급 받으신 경우, 도메인을 검증하므로 등록한 도메인이 포함된 referer로 설정해야합니다. 일치하지 않으면 가 반환됩니다.
참고
체험하기 키는 별도연동 코드에는 위 연동용 clientKey 를, 데모 콘솔 탭의 체험하기에는 전용 키를 씁니다.
환경별 키 분리테스트와 라이브는 clientKeycst_idcustKey 가 모두 다릅니다. 환경변수로 분리해두면 같은 인증 오류를 피할 수 있습니다.
통신 보안파트너사는 TLS v1.2 이상 / SSL 보안 통신(HTTPS)을 필수적으로 적용해야 합니다.
테스트 환경카드는 실제 결제 후 24시간 내 자동 취소, 계좌는 실제 출금 없음문서 바로가기웹훅결제 완료, 취소 완료, 결제수단 등록, 결제수단 해지 결과를 받아 누락을 막습니다문서 바로가기

파라미터 값 유의사항

Emoji 등 한글, 영어, 숫자를 제외한 문자를 파라미터에 포함할 경우, 결제 또는 결제내역 조회가 정상적으로 처리되지 않을 수 있습니다.
모든 파라미터 값에는 이모지 사용을 지양해 주시기 바라며 파라미터에 사용 가능한 특수문자는 아래와 같습니다.

`!@#$%^*()_=-[]{};:./?
샘플 코드javanodereactpythonphp

01결제창 호출

client
주의
비밀번호 간편결제와 함께 쓸 수 없음간편페이 정기(빌링) 결제는 비밀번호 간편결제(pwd)와 함께 사용할 수 없습니다. 결제창에서 PCD_SIMPLE_FLAG=Y 와 PCD_PAYER_AUTHTYPE=pwd 를 함께 설정하면 PMCD0015 가 반환됩니다.

간편페이 정기(빌링) 결제에 필요한 주요 Request 파라미터입니다.
공통 파라미터는 국내 카드 정기(빌링) 결제 파라미터를 함께 확인해주세요.

파라미터타입설명값 예시
clientKey필수String
128		파트너 인증을 위한 클라이언트키입니다.test_DF55F29DA654A8CBC0F0A9DD4B556486
PCD_PAY_TYPE필수String
20		결제수단입니다. 간편페이 정기(빌링) 결제는 card로 설정합니다.card
PCD_PAY_WORK필수String
20		카드 인증과 빌링키 발급 절차를 진행하도록 CERT로 설정합니다.빌링키만 발급하는 AUTH는 지원하지 않습니다.CERT
PCD_CARD_VER필수String
2		빌링 결제방식인 01로 설정합니다.01
PCD_EASYBILL_FLAG필수String
1		간편페이 정기(빌링) 결제창을 호출하기 위한 설정값입니다.결제창에서 빌링키를 최초 발급할 때 반드시 Y로 설정합니다.Y
PCD_PAY_GOODS필수String
255		상품명입니다.테스트 상품
PCD_PAY_TOTAL필수Number
10		총 결제금액입니다.1000
PCD_RST_URL필수String카드 인증 결과가 POST 방식으로 전송되는 URL입니다.https://result-domain.com
PCD_PAY_METHODString
20		발급받을 간편페이 빌링키와 결제창에 표시할 수단을 선택합니다.네이버페이: naverPay카카오페이: kakaoPay두 수단 모두 등록된 카드만 지원하며 머니·포인트는 사용할 수 없습니다.한 가지 수단만 계약된 파트너사는 생략할 수 있으며, 계약된 수단만 표시됩니다.naverPay kakaoPay
PCD_PAYER_NONumber
18		파트너(상점)에서 관리하는 회원번호입니다.1234
주의결제 요청 화면과 결제창이 서로 다른 브라우저나 웹뷰면 이 발생합니다. SameSite 설정도 함께 확인하세요.

02최초 인증 결과 수신

server

카드 인증이 완료되면 인증 결과가 POST 방식으로 PCD_RST_URL에 전달됩니다.
이 단계는 인증 결과이며 결제가 완료된 상태가 아닙니다.
응답받은 PCD_PAY_COFURL로 발급을 위한 결제 승인을 요청해주세요.
같은 카드라도 발급 요청에 따라 서로 다른 PCD_PAYER_ID가 발급될 수 있으므로,
카드번호가 아닌 PCD_PAYER_ID를 파트너사 회원 및 간편페이 수단과 함께 관리해주세요.

주의
callbackFunction 안에 넣으면 안 되는 것callbackFunction 내부에 아래 요소가 있으면 XSS 공격으로 인식되어 요청이 차단될 수 있습니다.
HTML 주석(<!-- -->), <div> <span> 같은 HTML 태그, <iframe> 태그. 필요하면 순수 텍스트로 바꿔 주세요.
참고
PCD_RST_URL 경로에 따라 달라지는 결제창상대경로(예: /result)는 PC 에서 레이어팝업, 모바일에서 새 탭(새 창)으로 열립니다. PC 에서 범용적으로 쓰는 방식입니다.
절대경로(예: https://your-domain.com/result)는 결제창으로 화면이 바로 전환(다이렉트)됩니다. 모바일에 권장합니다.
모바일에서 팝업 차단이 켜져 있으면 상대경로 방식은 창이 열리지 않습니다. 카카오톡, 페이스북 같은 인앱 브라우저에서 결제가 일어나면 절대경로(다이렉트)를 권장합니다.
SPA 에서 결과 받기SPA 처럼 화면 이동 없이 결과를 받으려면 결제창 요청에 callbackFunction 을 추가합니다. PCD_RST_URL 을 상대경로로 지정한 경우에만 쓸 수 있습니다.
저장해두기PCD_AUTH_KEY03 발급을 위한 결제 승인 요청PCD_PAY_REQKEY03 발급을 위한 결제 승인 요청PCD_PAYER_ID03 발급을 위한 결제 승인 요청

03발급을 위한 결제 승인 요청

server
받아서 넣기PCD_AUTH_KEY02 최초 인증 결과 수신PCD_PAY_REQKEY02 최초 인증 결과 수신PCD_PAYER_ID02 최초 인증 결과 수신
저장해두기PCD_PAY_METHOD05 빌링키로 재결제PCD_PAYER_ID05 빌링키로 재결제
POST테스트https://democpay.payple.kr/php/PayCardConfirmAct.php?ACT_=PAYM
POST라이브https://cpay.payple.kr/php/PayCardConfirmAct.php?ACT_=PAYM

빌링키 인증 결과로 받은 인증값을 이용해 최초 결제를 승인합니다.
실제 요청 URL은 PCD_PAY_COFURL 응답값을 사용해주세요.

파라미터타입설명값 예시
PCD_CST_ID필수String
12		파트너 인증을 위한 ID 입니다. 라이브 ID 는 계약이 완료되어야 발급 가능합니다.test
PCD_CUST_KEY필수String
255		파트너 인증을 위한 키입니다. 라이브 키는 계약이 완료되어야 발급 가능합니다.외부에 노출되면 안되는 정보입니다. 보안에 유의해주세요.abcd1234567890
PCD_AUTH_KEY필수String인증결과로 수신하는 파트너 인증 키입니다.
파트너 인증 응답으로 받은 값을 그대로 사용해주세요.		K0VnW…
PCD_PAY_REQKEY필수String
255		인증결과로 수신하는 결제 키입니다.Vnx...
PCD_PAYER_ID필수String
255		간편페이 정기(빌링) 결제 시 필요한 빌링키입니다.OVA3…

04파트너 인증 요청

server
저장해두기cst_id05 빌링키로 재결제custKey05 빌링키로 재결제AuthKey05 빌링키로 재결제
POST테스트https://democpay.payple.kr/php/auth.php
POST라이브https://cpay.payple.kr/php/auth.php

빌링키 승인 요청 시 요구되는 파트너 인증에 필요한 Request 파라미터는 아래와 같습니다.

파라미터타입설명값 예시
cst_id필수String
12		파트너 인증을 위한 ID 입니다. 라이브 ID 는 계약이 완료되어야 발급 가능합니다.test
custKey필수String
255		파트너 인증을 위한 키입니다. 라이브 키는 계약이 완료되어야 발급 가능합니다.외부에 노출되면 안되는 정보입니다. 보안에 유의해주세요.abcd1234567890
PCD_PAY_TYPE필수String
20		결제수단(카드/계좌)입니다.카드 : card / 계좌 : transfercard
PCD_SIMPLE_FLAG필수String
1		정기(빌링), 비밀번호 간편결제 시 필요한 설정값입니다.Y

05빌링키로 재결제

server
받아서 넣기PCD_CST_ID04 파트너 인증 요청PCD_CUST_KEY04 파트너 인증 요청PCD_AUTH_KEY04 파트너 인증 요청PCD_PAYER_ID03 발급을 위한 결제 승인 요청PCD_PAY_METHOD03 발급을 위한 결제 승인 요청
저장해두기PCD_PAYER_ID06 운영
POST테스트https://democpay.payple.kr/php/SimplePayCardAct.php?ACT_=PAYM
POST라이브https://cpay.payple.kr/php/SimplePayCardAct.php?ACT_=PAYM

실결제 승인 과정에서 필요한 Request 파라미터는 다음과 같습니다.

파라미터타입설명값 예시
PCD_CST_ID필수String
255		파트너 인증을 위한 ID 입니다.UFVNNVZ…
PCD_CUST_KEY필수String
255		파트너 인증 후 수신한 키입니다.T3JzRkp5L…
PCD_AUTH_KEY필수String인증완료 후 수신하는 파트너 인증 키입니다.
파트너 인증 응답으로 받은 값을 그대로 사용해주세요.		K0VnW…
PCD_PAY_TYPE필수String
20		카드 결제수단 중 앱카드, 정기(빌링), 비밀번호 간편결제 방식을 선택합니다.카드: card / 계좌: transfercard
PCD_PAYER_ID필수String
255		간편페이 정기(빌링) 결제 시 필요한 빌링키입니다.PCD_PAY_METHOD를 전송하는 경우 동일한 간편페이 수단으로 발급된 값을 전송해주세요.OVA3…
PCD_PAY_GOODS필수String
255		상품명입니다.
Emoji 또는 허용되지 않은 특수문자(& ' " \ < > | \n \r\n , +)만으로 구성된 값은 입력할 수 없습니다.		테스트 상품
PCD_SIMPLE_FLAG필수String
1		정기(빌링) 결제 시 필요한 설정값입니다.Y
PCD_PAY_TOTAL필수Number
10		총 결제금액입니다.1000
PCD_PAY_METHODString
20		사용할 간편페이 수단을 명시하려는 경우 선택적으로 전송합니다. 미전송 시 PCD_PAYER_ID에 연결된 간편페이 수단으로 처리됩니다.네이버페이: naverPay카카오페이: kakaoPay전송하는 경우 PCD_PAYER_ID 발급 시 선택한 간편페이 수단과 동일하게 설정해주세요.naverPay kakaoPay
PCD_PAY_OIDString
64		승인 요청 건의 주문번호로 파트너(상점)에서 생성한 거래의 고유 식별번호입니다.
중복되지 않는 고유한 값을 발급해야 하며, 미전송 시 페이플에서 발급한 주문번호를 응답합니다. 한글은 사용할 수 없으며 영문, 숫자, 특수문자(-, _, .)만 사용 가능합니다.		order12345
PCD_PAYER_NONumber
18		파트너(상점)에서 이용하는 회원번호입니다.1234
PCD_PAYER_NAMEString
80		구매자 이름입니다.
Emoji 또는 허용되지 않은 특수문자(& ' " \ < > | \n \r\n , +)만으로 구성된 값은 입력할 수 없습니다.		김이플
PCD_PAYER_HPString
15		구매자 휴대폰번호입니다. 구매자에게 결제된 상점정보를 알림톡으로 발송합니다.01012345678
PCD_PAYER_EMAILString
100		구매자 이메일입니다. 결제완료, 취소 메일이 발송됩니다.complete@payer-email.com
PCD_PAY_ISTAXString
1		과세 여부입니다. 기본값은 Y 이며, 유형별로 아래와 같이 설정해주세요.과세, 복합과세 : Y비과세: NY
PCD_PAY_TAXTOTALNumber
9		복합과세 주문 시에만 이용하며, 복합과세 주문의 부가세를 설정합니다.예: 총 결제금액(PCD_PAY_TOTAL) 10,000원 중 복합과세 주문의 부가세가 500원이면 500으로 설정500
PCD_USER_DEFINE1String
2048		파트너(상점)에서 입력한 값을 그대로 응답합니다.define1
PCD_USER_DEFINE2String
2048		파트너(상점)에서 입력한 값을 그대로 응답합니다.define2

06운영

ops

결제가 끝나면 취소, 조회, 해지가 따라옵니다.
실제 연동 흐름상 결제 기능과 연계되는 부분이므로 이어 설명합니다.

POST테스트https://democpay.payple.kr/php/account/api/cPayCAct.php
POST라이브https://cpay.payple.kr/php/account/api/cPayCAct.php
결제 연동과 관련된 무엇이든 물어보세요