결제창 커스텀 - 국내(앱카드/간편페이)

국내(앱카드/간편페이) 결제창의 색상, 버튼 모양, 결제수단 배치 등을 파트너 화면에 맞게 바꾸는 방법입니다.
스크립트 파라미터로 개별 결제 세션 단위로 다르게 적용할 수 있습니다.

연동하기

국내 앱카드(간편페이), 간편페이 정기(빌링) 결제창을 커스텀 할 수 있는 메뉴입니다.
아래 설명을 확인하시고 결제창 디자인을 자유롭게 관리해보세요.

결제창 커스텀 기능을 파라미터 적용 전 직접 체험해보세요.
색상, 버튼 모양, 결제수단 배치 등 다양한 설정을 변경하고 결제창 미리보기를 실시간으로 확인할 수 있습니다.

사전 준비

결제창 커스텀 기능은 국내(앱카드/간편페이) 결제창 연동이 완료된 파트너에게 제공됩니다.
아직 연동을 진행하지 않으셨다면 앱카드 결제 연동 트랙을 먼저 확인해주세요.

커스텀 전 참고 사항

결제창 커스텀은 2가지 방식을 지원합니다.

페이플 파트너 관리자에서 직접 커스텀 후 저장
결제창 호출 스크립트의 파라미터로 옵션 추가 후 호출

파트너 관리자에 지정해둔 스타일이 기본적으로 먼저 적용되며, 파라미터로 전달된 옵션 값이 덮어쓰여지게 됩니다.
결제 고객 유형별로 결제창을 커스텀하고 싶다면, 2번 방식을 활용해보세요.

해당 문서는 2번 스크립트 방식에 대해 설명합니다.
스크립트 커스텀 방식을 사용하기 위해선 파트너관리자 > 신용카드 > 결제창 커스텀 페이지 접근 후,
스크립트 방식 사용 버튼을 활성화 해주세요.
파라미터 방식을 사용하지 않을 예정이라면, 결제창 호출 시 넣는 파라미터를 제거하거나 파트너 관리자에서 스크립트 방식 사용 버튼을 비활성화해주세요.

주의

스크립트 방식 사용 버튼이 활성화 되지 않은 상태로 스크립트 방식을 사용하게 되면, 결제창 호출 시 넣어둔 커스텀 값은 적용되지 않습니다.

스크립트 예제

결제창 호출 파라미터에 theme을 함께 전달합니다.
그 외 결제 요청 파라미터는 국내 카드 결제창 호출 파라미터를 참고해주세요.

주의

theme 파라미터 값은 8kbyte 이상 전달 시 무시됩니다.
커스텀이 문제 없이 적용될 수 있도록 정해진 형식을 지켜 전달해주세요.

payment.html

<!DOCTYPE html><html>    <head>        <meta charset="UTF-8">        <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?v=%datetime%"></script>    </head>    <body>        <!-- 주문서 내 결제하기 버튼 -->        <button id="btnPayment">결제하기</button>        <script>            // 결제 세션에 적용시킬 커스텀 Theme            // 📄 파라미터별 가이드 참고            const theme = {                "colors": {                    "brand": "#7852e8",                    "background": "#FFFFFF"                },                "buttons": {                    "shape": "default"                },                "paymentMethods": {                    "column": "2",                    "order": ["appCard", "naverPay", "kakaoPay"]                },                "cardList": {                    "renderAs": "dropdown"                },                "amountOnSubmit": "Y"            }             // 결제 요청 파라미터            // 📄 국내 카드 결제창 호출 파라미터 참고            const params = {                clientKey: "test_DF55F29DA654A8CBC0F0A9DD4B556486",                PCD_PAY_TYPE: "card",                PCD_PAY_WORK: "CERT",                PCD_CARD_VER: "02",                PCD_PAY_GOODS: "커스텀 체험 상품",            }             const handlePayment = (amount, goods_name) => {                window.PaypleCpayAuthCheck({                    ...params,                    theme,                    PCD_PAY_TOTAL: amount,                    PCD_PAY_GOODS: goods_name,                });            }             document.getElementById('btnPayment').addEventListener('click', function (event) {                handlePayment(1000, '커스텀 체험 상품');            });        </script>    </body></html>

theme 기본 형태

별도로 값을 지정하지 않은 항목은 아래 기본값이 적용됩니다.

theme.json

{    "colors": {        "brand": "#121212",        "background": "#FFFFFF"    },    "buttons": {        "shape": "default"    },    "paymentMethods": {        "column": "3",        "order": ["appCard", "naverPay", "kakaoPay"]    },    "cardList": {        "renderAs": "button"    },    "amountOnSubmit": "N"}

파라미터별 가이드

theme 객체는 아래 항목들의 조합으로 구성되며, 하위 key는 들여쓰기로 상위 Object와의 관계를 표기했습니다.

색상

파라미터	타입	값 예시	설명
colors	Object		색상 관련 설정을 묶은 객체입니다.
brand	string	#121212 (기본값)	결제 버튼, 체크박스, 라디오 버튼 등 주요 UI 요소에 적용됩니다. 색상 밝기에 따라 버튼 내 텍스트 색상(흰색/검정)이 자동으로 결정됩니다.
background	string	#FFFFFF (기본값)	결제창 전체 배경 색상을 설정합니다.

참고

상품정보 및 기본 텍스트의 가독성을 떨어트리지 않도록 조정해주세요.

theme.json

{    "colors": {        "brand": "#121212",        "background": "#FFFFFF"    }}

버튼 모양

파라미터	타입	값 예시	설명
buttons	Object		버튼 모양 설정을 묶은 객체입니다.
shape	string	default (기본값)	약간 둥근 모서리의 기본 버튼 형태입니다.
		rectangle	모서리가 없는 직각 사각형 버튼입니다.
		round	완전히 둥근 형태의 버튼입니다.

theme.json

{    "buttons": {        "shape": "default"    }}

결제수단

파라미터	타입	값 예시	설명
paymentMethods	Object		결제수단 레이아웃 설정을 묶은 객체입니다.
column	string	3 (기본값)	1열, 2열, 3열 중 선택합니다. 활성화된 결제수단이 설정값보다 적을 경우 자동으로 조정됩니다. 결제수단 3가지를 사용하는 파트너사가 2열로 설정하면 가장 맨 앞 결제수단이 강조됩니다.
order	string[]	[appCard, naverPay, kakaoPay] (기본값)	결제수단의 노출 순서를 변경합니다.

theme.json

{    "paymentMethods": {        "column": "3",        "order": ["appCard", "naverPay", "kakaoPay"]    }}

카드 목록앱카드 전용

파라미터	타입	값 예시	설명
cardList	Object		카드 목록 설정을 묶은 객체입니다.
renderAs	string	button (기본값)	카드사 로고를 그리드 버튼으로 표시합니다. 처음에는 일부 카드사만 노출되고, 더보기 버튼을 통해 전체 카드사를 확인할 수 있습니다.
renderAs	string	dropdown	드롭다운 선택 UI로 카드사를 선택합니다.

theme.json

{    "cardList": {        "renderAs": "button"    }}

결제 버튼

파라미터	타입	값 예시	설명
amountOnSubmit	string	N (기본값)	버튼에 결제 금액 없이 텍스트만 표시됩니다. 예시: 결제하기
amountOnSubmit	string	Y	버튼에 결제 금액이 함께 표시됩니다. 예시: 19,900원 결제하기

theme.json

{    "amountOnSubmit": "N"}