해외 카드 정기결제

구매자가 페이플 결제창에서 카드를 한 번 등록하면 이후부터는 별도 인증없이 결제 요청이 가능합니다.

00연동 준비

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

스크립트 정보

사전 로드 (jQuery)<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>

테스트용<script src="https://demo-gpay.payple.kr/common/js/gpay-1.0.1.js"></script>

라이브용<script src="https://gpay.payple.kr/common/js/gpay-1.0.1.js"></script>

테스트 환경 접속 정보

접속 도메인https://demo-api.payple.kr

service_iddemo

service_keyabcd1234567890

codeas12345678

참고

환경별 키 분리테스트와 라이브는 service_idservice_key 가 다릅니다. 환경변수로 분리해두세요.

통신 보안파트너사는 TLS v1.2 이상 / SSL 보안 통신(HTTPS)을 필수적으로 적용해야 합니다.

연동 전 확인사항code, 국내 카드 화이트리스트, 화이트(White) IP 등록, 위험국가 리스트문서 바로가기 웹훅결제 완료, 취소 완료 결과를 받아 누락을 막습니다문서 바로가기

샘플 코드java node react python php

01파트너 인증 요청

server

참고

매 결제마다 새 토큰파트너 인증은 매 결제 요청마다 필요합니다. 발급된 토큰(access_token)은 10분간 유효합니다.

POST테스트https://demo-api.payple.kr/gpay/oauth/1.0/token

POST라이브https://api.payple.kr/gpay/oauth/1.0/token

결제창 호출을 위한 파트너 인증에 필요한 Request 파라미터는 아래와 같습니다.

파라미터	타입	설명	값 예시
service_id필수	String 20	파트너 인증을 위한 ID 입니다. 라이브 ID 는 계약이 완료되어야 발급 가능합니다.	demo
service_key필수	String 128	파트너 인증을 위한 키입니다. 라이브 키는 계약이 완료되어야 발급 가능합니다.외부에 노출되면 안되는 정보입니다. 보안에 유의해주세요.	abcd1234567890
code필수	String 10	파트너 인증에 필요한 토큰을 확인하는 용도로 사용되며, 파트너(상점)가 직접 생성하여 전송해야 하는 중요한 요소입니다.영문+숫자 조합 10자리로 구성되어야 합니다.	as12345678

02결제창 호출

client

아래는 결제창 호출 시 사용 가능한 Request 파라미터 목록입니다.

파라미터	타입	설명	값 예시
Authorization필수	String 500	파트너 인증 후 발급받은 access_token 입니다.
service_id필수	String 20	파트너 인증을 위한 ID 입니다.라이브 ID 는 계약이 완료되어야 발급 가능합니다.	demo
comments필수	String 200	상품명입니다.	테스트 상품
totalAmount필수	String 10	결제금액입니다.외화(USD, JPY)는 소수점 둘째 자리까지만 허용원화(KRW)는 정수만 가능(소수점 불가)	0.10
currency필수	String 3	결제통화입니다.가능한 통화는 KRW, USD, JPY 이며, 통화별 파트너(상점) 계정 발급이 필요테스트 환경에서는 USD 만 가능	USD
resultUrl필수	String 500	결제 정보가 성공적으로 입력된 경우, 인증 결과가 POST 방식으로 전송됩니다.	/result
payCls필수 - 테스트 시	String 10	테스트 서버로 결제요청 시에 필요한 값입니다.	demo
service_oid	String 128	주문번호입니다. 파트너(상점)에서 생성한 거래에 대한 고유식별번호입니다. 중복되지않는 고유한 값을 발급해야하며, 미전송 시 페이플에서 발급한 주문번호를 응답합니다.길이는 서버에서 바이트 기준으로 검사합니다. 한글은 1자가 3바이트입니다.	order12345
firstName	String 25	카드회원의 이름입니다.길이는 서버에서 바이트 기준으로 검사합니다. 한글은 1자가 3바이트입니다.	iple
lastName	String 25	카드회원의 성입니다.길이는 서버에서 바이트 기준으로 검사합니다. 한글은 1자가 3바이트입니다.	Kim
email	String 250	구매자 이메일입니다. 결제완료, 취소 이메일이 발송됩니다.	complete@payer-email.com
isDirect	String 1	결제창 호출 방식입니다.Y : 다이렉트 / 공란 : 팝업	Y
country	String 2	청구지 주소 - 국가코드입니다.카드회원의 청구지 주소가 없으면 발급사 거절 확률이 높아집니다.표준국가코드(ISO 3166-1)에서 정의된 2자리의 국가코드를 입력해야합니다. 상세내용은 여기에서 확인 가능합니다.청구지 주소는 country, administrativeArea, locality, address, postalCode 를 모두 보낼 때만 적용됩니다. 하나라도 빠지면 청구지 주소가 반영되지 않습니다.	US
administrativeArea	String 2	청구지 주소 - 행정구역 코드입니다.country가 미국(US) 또는 캐나다(CA)인 경우 필수로 입력해야하는 값입니다. 상세내용은 여기에서 확인 가능합니다.	NY
locality	String 32	청구지 주소 - 시/군/구 입니다.영문, 공백과 , . - 만 사용할 수 있습니다.	New York
address	String 40	청구지 주소 - 도로명입니다.영문, 숫자, 공백과 _ - . , 만 사용할 수 있습니다.	1000 5th Ave
postalCode	String 7	청구지 주소 - 우편번호입니다.영문, 숫자만 사용합니다. 그 외 문자는 결제창이 제거합니다.	10028
serviceDefine	String 500	사용자 정의 파라미터입니다. 파트너(상점)에서 보낸 값 그대로 반환됩니다.	We help our partners grow.

03결제결과 수신

server

결제 정보가 성공적으로 입력된 경우, 인증 결과는 POST 방식으로 resultUrl로 전송됩니다.

저장해두기billing_key05 빌링키로 승인 요청

04재결제를 위한 파트너 인증 요청

server

빌링키로 승인을 요청하기 전에 새 토큰을 발급받습니다. 1. 파트너 인증 요청과 같은 API 이며, 결제창 호출 때 받은 토큰은 다시 쓰지 않습니다.

POST테스트https://demo-api.payple.kr/gpay/oauth/1.0/token

POST라이브https://api.payple.kr/gpay/oauth/1.0/token

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

파라미터	타입	설명	값 예시
service_id필수	String 20	파트너 인증을 위한 ID 입니다. 라이브 ID 는 계약이 완료되어야 발급 가능합니다.	demo
service_key필수	String 128	파트너 인증을 위한 키입니다. 라이브 키는 계약이 완료되어야 발급 가능합니다.외부에 노출되면 안되는 정보입니다. 보안에 유의해주세요.	abcd1234567890
code필수	String 10	파트너 인증에 필요한 토큰을 확인하는 용도로 사용되며, 파트너(상점)가 직접 생성하여 전송해야 하는 중요한 요소입니다.영문+숫자 조합 10자리로 구성되어야 합니다.	as12345678

05빌링키로 승인 요청

server

파트너 인증 후 REST API를 활용하여 빌링키를 통한 승인 요청이 이루어지면, 이에 따른 실결제가 완료됩니다.

받아서 넣기billing_key03 결제결과 수신

저장해두기billing_key06 운영

POST테스트https://demo-api.payple.kr/gpay/billingKey

POST라이브https://api.payple.kr/gpay/billingKey

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

파라미터	타입	설명	값 예시
service_id필수	String 20	파트너 인증을 위한 ID 입니다.라이브 ID 는 계약이 완료되어야 발급 가능합니다.	demo
billing_key필수	String 128	빌링키입니다.	MlNCQ0pHMn…
comments필수	String 200	상품명입니다.	테스트 상품
totalAmount필수	String 10	결제금액입니다.외화(USD, JPY)는 소수점 둘째 자리까지만 허용원화(KRW)는 정수만 가능(소수점 불가)	0.10
currency필수	String 3	결제통화입니다.가능한 통화는 KRW, USD, JPY 이며, 통화별 파트너(상점) 계정 발급이 필요테스트 환경에서는 USD 만 가능	USD
resultUrl	String 500	보내면 응답의 resultUrl 로 그대로 돌려줍니다.빌링키 승인 결과는 이 API 의 응답(JSON)으로 바로 받습니다. 별도 주소로 전송되지 않습니다.	/result
service_oid	String 128	주문번호입니다. 파트너(상점)에서 생성한 거래에 대한 고유식별번호입니다. 중복되지않는 고유한 값을 발급해야하며, 미전송 시 페이플에서 발급한 주문번호를 응답합니다.길이는 서버에서 바이트 기준으로 검사합니다. 한글은 1자가 3바이트입니다.	order12345
firstName	String 25	카드회원의 이름입니다.길이는 서버에서 바이트 기준으로 검사합니다. 한글은 1자가 3바이트입니다.	iple
lastName	String 25	카드회원의 성입니다.길이는 서버에서 바이트 기준으로 검사합니다. 한글은 1자가 3바이트입니다.	Kim
email	String 250	구매자 이메일입니다. 결제완료, 취소 이메일이 발송됩니다.	complete@payer-email.com
country	String 2	청구지 주소 - 국가코드입니다.카드회원의 청구지 주소가 없으면 발급사 거절 확률이 높아집니다.표준국가코드(ISO 3166-1)에서 정의된 2자리의 국가코드를 입력해야합니다. 상세내용은 여기에서 확인 가능합니다.청구지 주소는 country, administrativeArea, locality, address, postalCode 를 모두 보낼 때만 적용됩니다. 하나라도 빠지면 청구지 주소가 반영되지 않습니다.	US
administrativeArea	String 2	청구지 주소 - 행정구역 코드입니다.country가 미국(US) 또는 캐나다(CA)인 경우 필수로 입력해야하는 값입니다. 상세내용은 여기에서 확인 가능합니다.	NY
locality	String 32	청구지 주소 - 시/군/구 입니다.영문, 공백과 , . - 만 사용할 수 있습니다.	New York
address	String 40	청구지 주소 - 도로명입니다.영문, 숫자, 공백과 _ - . , 만 사용할 수 있습니다.	1000 5th Ave
postalCode	String	청구지 주소 - 우편번호입니다.영문, 숫자, 공백과 _ - . , 만 사용할 수 있습니다.	10028
serviceDefine	String 500	사용자 정의 파라미터입니다. 파트너(상점)에서 보낸 값 그대로 반환됩니다.	We help our partners grow.

06운영

ops

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

POST테스트https://demo-api.payple.kr/gpay/cancel

POST라이브https://api.payple.kr/gpay/cancel