결제창 연동
국내 카드결제〉앱카드(간편페이) 결제
연동하기
국내 카드사의 앱카드 및 간편페이(네이버페이, 카카오페이)를 통해 결제하는 방식입니다.
국내에서 발급된 모든 신용, 체크, 법인카드 결제가 가능합니다.
연동흐름
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_CARD_VER을 "02" 로 설정합니다.
1.5 결제창 호출
PaypleCpayAuthCheck(obj) 함수 호출 시 결제창이 띄워집니다.
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 = "card";
17 PCD_PAY_WORK = "CERT";
18 PCD_CARD_VER = "02";
19 PCD_PAY_GOODS = "테스트 상품";
20 PCD_PAY_TOTAL = 1000;
21 PCD_RST_URL = "/result";
22 }
23
24 const handlePayment = (amount, goods_name) => {
25 window.PaypleCpayAuthCheck({
26 ...params,
27 PCD_PAY_TOTAL: amount,
28 PCD_PAY_GOODS: goods_name,
29 });
30 }
31
32 document.getElementById('btnPayment').addEventListener('click', function (event) {
33 handlePayment(1000, '테스트 상품');
34 });
35 </script>
36 </body>
37</html>복사가 완료되었습니다.
2. 인증결과 수신
server결제 정보가 성공적으로 입력된 경우, 인증 결과는 POST 방식으로
PCD_RST_URL로 전송됩니다. 경로지정 방식에 따라 결제창이 다르게 띄워집니다.
| 경로 | 방식 |
|---|---|
| 상대경로 | 레이어팝업 PC 권장 PC 환경에서 범용적으로 사용하는 방식입니다. |
| 절대경로 | 다이렉트 보통 PC에서는 레이어팝업을 사용하기에 고객에게 생소할 수 있습니다. |
| 경로 | 방식 |
|---|---|
| 상대경로 | 새탭(새창)
|
| 절대경로 | 다이렉트 MO권장 모바일 환경설정에 팝업차단 설정이 ON되어 있어도 결제 할 수 있습니다 |
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복사가 완료되었습니다.
SPA(Single Page Application)로 인증 결과를 수신하려면, 콜백 함수
파라미터를 추가해주세요.
관련된 자세한 내용은 페이플 지니를 참고해주세요.
·주의사항
- callbackFunction을 사용할 경우, 함수 내부에 다음과 같은 요소들이 포함되면 XSS 공격으로 인식되어 요청이 차단될 수 있습니다.
- 아래와 같은 요소들을 제거하거나 사용하지 않는 형태로 코드를 작성한 후 시도해 주시기 바랍니다.
- HTML 주석 태그 : <-- 주석내용 -->와 같은 주석은 XSS 공격으로 간주될 수 있습니다.
callbackFunction을 사용할 때는 이러한 주석 태그를 제거해 주시기 바랍니다. - HTML 태그 : <div>, <span> 등의 일반적인 HTML 태그도 코드 내에 포함될 경우 XSS 공격으로
인식될 수 있으므로 주의가 필요합니다.
필요한 경우 순수 텍스트로 변환하거나 HTML 태그 사용을 자제해 주시기 바랍니다. - iframe 태그 : <iframe> 태그는 외부 콘텐츠를 삽입할 때 자주 사용되지만, XSS 공격에 악용될 수 있습니다.
callbackFunction 내부에서 iframe 태그를 사용하지 않도록 해주시기 바랍니다.
- HTML 주석 태그 : <-- 주석내용 -->와 같은 주석은 XSS 공격으로 간주될 수 있습니다.
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}복사가 완료되었습니다.
웹훅(Webhook)이 등록되었으면 등록한 웹훅 URL로도 결과가 수신됩니다.
3. API로 승인 요청
server3.1 PCD_CUST_KEY 확인
계약 완료 후 페이플 담당자에게 전달받은 PCD_CUST_KEY를 확인해주세요.
·주의사항
PCD_CUST_KEY 외부에 노출되면 안되는 정보입니다. 보안에 유의해주세요.
3.2 승인 요청
REST API를 통한 승인 요청이 이루어지면, 해당 요청에 따라 실제 결제가 완료됩니다. 필히 원 주문 정보를 정확하게 확인해주세요.
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}·주의사항
·Referer 필드에는 페이플에 등록된 파트너(상점)의 도메인을 정확히 입력해주세요. 도메인이 일치하지 않을 경우, ‘AUTH0004’ 오류 메시지가 반환됩니다.
·인증 결과 수신 후 승인 요청은 10분 이내에 완료해야 합니다. 초과 시 거래 세션이 만료되어 ‘PCCFD001’ 오류 메시지가 반환됩니다.