해외 카드 정기결제
구매자가 페이플 결제창에서 카드를 한 번 등록하면 이후부터는 별도 인증없이 결제 요청이 가능합니다.
00연동 준비
페이플이 제공하는 테스트 정보를 통해 계약 전 단계에서도 누구나 연동 체험이 가능합니다.
테스트 환경 접속 정보
접속 도메인
https://demo-api.payple.krservice_id
demoservice_key
abcd1234567890code
as12345678참고
연동 전 확인사항code, 국내 카드 화이트리스트, 화이트(White) IP 등록, 위험국가 리스트문서 바로가기웹훅결제 완료, 취소 완료 결과를 받아 누락을 막습니다문서 바로가기환경별 키 분리테스트와 라이브는 service_idservice_key 가 다릅니다. 환경변수로 분리해두세요.
통신 보안파트너사는 TLS v1.2 이상 / SSL 보안 통신(HTTPS)을 필수적으로 적용해야 합니다.
01파트너 인증 요청
server참고
매 결제마다 새 토큰파트너 인증은 매 결제 요청마다 필요합니다. 발급된 토큰(
access_token)은 10분간 유효합니다.POST테스트
https://demo-api.payple.kr/gpay/oauth/1.0/tokenPOST라이브
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 |
| 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/tokenPOST라이브
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/billingKeyPOST라이브
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 |
| 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/cancelPOST라이브
https://api.payple.kr/gpay/cancel