본 문서에서는 페이플 해외결제창을 결제부터 취소까지 빠르게 연동해 볼 수 있는 Quick Guide를 안내합니다.
1. 해외카드 결제 프로세스 개요
해외카드 결제의 프로세스는 다음과 같이 진행됩니다.
2. White IP 등록
•
페이플 해외카드 결제 - 운영(REAL)에서는 등록되어 있는 IP와의 통신만 허용하고 있습니다.
◦
테스트(demo)는 별도의 White IP 등록없이 해외카드 결제를 위한 통신이 가능합니다.
White IP 등록은 파트너 인증 토큰발급을 위해 필요한 절차이며,
파트너 인증 토큰 발급 요청시에는 등록한 IP로 통신해야합니다.
3. 해외카드 결제
3-1. 파트너 인증 토큰발급
Partner Server Side
•
파트너는 결제창을 고객에게 띄워주기 위한 사전단계인 파트너 인증 프로세스를 진행해야 합니다.
•
파트너 인증을 위한 토큰 발급은 결제요청 전 필수로 진행해야합니다.
발급받은 access_token은 결제요청 시 필요하며,
토큰의 유효기간(10분)이 지나면 토큰을 다시 발급받으셔야 합니다.
※ 토큰의 유효기간인 10분이 지나면 결제가 진행되지 않으니 유의해주세요!
파트너 인증 토큰발급 요청시에는 등록한 IP(White IP)와의 통신만 허용합니다.
이외 IP로 파트너 인증 토큰발급 요청을 할 경우 거부되니 주의해주세요.
Partner Authorization Request Parameters
code는 반드시 영문자+숫자만 포함하여 10자만 입력해야합니다.
Table
Search
Request sample
•
Header 정보
/*
* Request HTTP URL
* TEST : https://demo-api.payple.kr/gpay/oauth/1.0/token
* REAL : https://api.payple.kr/gpay/oauth/1.0/token
*/
Request HTTP URL: "https://demo-api.payple.kr/gpay/oauth/1.0/token"
HTTP Method: POST
Content-Type: application/json
Cache-Control: no-cache
JSON
복사
•
Body(Payload) 값
{
"service_id":"demo",
"service_key":"abcd1234567890",
"code":"as12345678"
}
JSON
복사
Partner Authorization Response Parameters
•
토큰발급 요청이 성공하면 페이플에서 파트너에 다음과 같은 성공 리턴을 드립니다.
Table
Search
Response sample
{
"result": "T0000",
"message": "Process Success",
"code": "as12345678",
"access_token": "eyJhbGciOiJzaGEyNT...",
"token_type": "Bearer",
"payCls": "demo", // 테스트 결제(결제창)인 경우에만 필요
"expires_in": "600"
}
JSON
복사
result= "T0000", message= "Process Success"인 경우 요청 성공으로 판단합니다.
[테스트 서버 유의사항]
테스트 서버(demo-api.payple.kr)로 파트너 인증 토큰발급 요청을 보내시는 경우에는
payCls값도 저장한 후 결제요청시 요청 파라미터로 함께 보내셔야 합니다.
테스트 결제시에 payCls값을 보내지 않으면, 테스트(TEST)서버가 아닌 운영(LIVE)서버로 결제 요청이 보내집니다.
같은 맥락으로, 실제 서비스 결제(LIVE)를 요청할 때에는 payCls를 보내면 안됩니다.
테스트와 운영 결제 요청을 반드시 구분해주세요!
발급받은 access_token은 결제 요청시 Authorization값으로 필요합니다.
3-2. 결제요청
Partner Client Side
•
파트너 인증이 완료되면 결제요청을 합니다.
Payple Global Payment Script
•
파트너 인증 토큰 발급 후 결제창을 호출할 수 있는 스크립트를 추가하여 페이플에 요청합니다.
@1/6/2023 이후로 해외결제 스크립트의 버전이 업그레이드 되었습니다!
기존에 사용중이였다면, 스크립트 버전에서 1.0.1로 반드시 수정해주시기 바랍니다.
// 서버별 페이플 해외결제 스크립트 추가
<script src="https://demo-gpay.payple.kr/common/js/gpay-1.0.1.js"></script> // 테스트(TEST)
<script src="https://gpay.payple.kr/common/js/gpay-1.0.1.js"></script> // 운영(REAL)
JavaScript
복사
•
페이플 해외카드 결제 스크립트를 추가한 후 결제요청 파라미터를 Object 객체에 담아 paypleGpayPaymentRequest(Object)를 호출하면 결제창이 열립니다.
결제창 요청 예시
// 페이플 해외카드 결제창 호출
function requsetGlobalPay() {
// obj에 결제요청 파라미터 저장
let obj = new Object();
/* 중략 */
// 결제요청 함수 호출
paypleGpayPaymentRequest(obj);
}
JavaScript
복사
JavaScript
Payment Request Parameters
파트너 인증 토큰 발급시 받은 access_token값을 Authorization에 넣어서 요청해주세요.
•
인증 토큰의 유효기간은 10분입니다.
•
한 번의 파트너 인증 토큰 발급으로 유효기간(10분) 이내에 결제를 완료해야 합니다.
[테스트 결제 유의사항]
1.
테스트 결제 환경 구분 payCls
•
테스트 서버(demo-api.payple.kr)로 파트너 인증 토큰발급 요청을 보내신 경우에는
파트너 인증 토큰 발급시 받은 payCls값을 요청 파라미터로 함께 보내셔야 합니다.
•
테스트 결제시에 payCls값을 보내지 않으면, 테스트(TEST)서버가 아닌 운영(LIVE)서버로 결제 요청이 보내집니다.
같은 맥락으로, 실제 서비스 결제(LIVE)를 요청할 때에는 payCls를 보내면 안됩니다.
•
테스트와 운영 결제 요청을 반드시 구분해주세요!
2.
테스트 계정(service_id = “demo”)으로 요청시 결제 통화(currency)
•
테스트 계정(demo)으로 결제요청 하는 경우, 결제 통화는 달러(USD)만 가능합니다.
•
원화(KRW)나 이외 값을 보낼 경우, 요청이 거부되니 유의해주세요!
요청 파라미터의 길이(Length)는 Byte 기준입니다.
- 한글의 경우, 1글자당 3Byte로 계산하여 최대 길이를 넘지 않게 보내시면 됩니다.
Table
Search
결제요청 파라미터 중 필수가 아닌 선택 파라미터를 보내시면 결제창에 미리 해당 값을 입력하는 기능을 수행합니다.
고객이 입력해야하는 필드값을 줄어들게 하는 효과가 있습니다.
(단, 결제창에 필드값만 해당 - service_oid , isDirect 제외)
Sample Code
// 서버별 페이플 해외카드 결제 스크립트 추가
<script src="https://demo-gpay.payple.kr/common/js/gpay-1.0.0.js"></script> // 테스트(TEST)
// <script src="https://gpay.payple.kr/common/js/gpay-1.0.0.js"></script> // 운영(REAL)
<script>
$(document).ready( function () {
$('#requestGlobalPay').on('click', function (event) {
let obj = new Object();
// Pay Request Parameters
obj.Authorization = "eyJhbGciOiJzaGEyNT..."
obj.service_id = "test";
obj.service_oid = "test120220608512351";
obj.comments = "테스트상품명";
obj.totalAmount = "0.10";
obj.currency = "USD";
obj.firstName = "Gildong";
obj.lastName = "Hong";
obj.email = "test@payple.kr";
obj.resultUrl = "http://test.shop.com";
obj.isDirect = "";
/*
* 테스트 결제인 경우에만 필수로 보내는 파라미터(payCls)
* payCls는 파트너 인증 토큰발급 응답값으로 반환되는 값이며,
* 테스트 결제시에만 필요합니다.
*/
obj.payCls = "demo"; // 파트너 인증 토큰발급 응답값으로 오는 payCls 그대로 전송
// 결제요청 함수 호출
paypleGpayPaymentRequest(obj);
});
});
</script>
...
<button id="requestGlobalPay">해외결제</button>
JavaScript
복사
3-3. 결제 진행
User Client Side
•
페이플에서 해외 결제창을 고객의 브라우저에 호출합니다.
•
고객은 결제창에서 결제정보를 입력하여 결제를 진행합니다.
3-4. 결제 결과 Return
Payple Server Side
•
고객이 결제창을 통한 결제를 모두 완료하면 페이플에서 고객의 결제창을 종료시킵니다.
•
resultUrl로 고객의 브라우저를 리다이렉트(Redirect) 처리합니다.
◦
결제결과는 resultUrl로 POST 전송되면서 리다이렉트(Redirect) 됩니다.
Payment Response Parameters
Table
Search
결제창 결제 완료 후 수신하는 결제 응답은 Depth가 없습니다.
이외 결제 및 API 요청시에는 Depth가 있을 수 있으며, 자세한 사항은 각 연동 문서에서 필히 확인해주시기 바랍니다.
Response sample
{
"type": "PAYMENT",
"result": "A0000",
"message": "처리 성공",
"resultUrl": "http://test.shop.com",
"api_id": "6548264741426583803027",
"api_date": "2022-06-10 11:01:17",
"service_oid": "test120220608512351",
"comments": "테스트상품명",
"pay_type": "card",
"card_number": "1234-****-****-7890",
"totalAmount": "0.10",
"currency": "USD",
"firstName": "Gildong",
"lastName": "Hong",
"email": "test@payple.kr",
"billing_key": "MlNCQ0pHMn...",
"submitTimeUtc": "2022-06-10 02:01:16",
"serviceDefine": "Service Define Test"
}
JSON
복사
•
Webhook URL 을 등록했다면 페이플에서 해당 URL로도 결과를 추가로 반환합니다.
페이플에서는 결제결과 수신 누락을 방지하기 위해 Webhook URL 등록을 권장합니다.
단, 테스트 서버에서는 별도의 계정을 발급받지 않는 한 Webhook URL 등록 및 테스트가 불가합니다.
3-5. 결과 처리
Partner Server Side
파트너사에서 페이플로부터 받은 결제 결과(Response)를 처리합니다.
결제 성공여부는 결제 결과 파라미터인 응답코드(result)를 보고 판단합니다.
•
result = "A0000" 인 경우 요청 성공으로 판단합니다.
•
result = "C0999" 인 경우 요청 실패로, 고객이 결제창을 종료하거나 여타 이유로 인해 결제창이 종료된 경우입니다.
◦
고객이 결제창을 종료한 경우: message = "고객이 결제창을 종료하였습니다." 혹은 "The client has closed the payment window."
•
이외 코드인 경우 요청 실패로 판단합니다.
요청이 성공했을 경우
1.
데이터 위변조 여부를 판별하기 위해 결제 결과로 리턴받은 totalAmount 값과 결제 요청했던 값을 대조하여 이상이 없음을 확인합니다.
2.
리턴받은 거래고유식별번호인 service_oid를 확인하여 요청했던 거래정보와 매칭시킵니다.
3.
거래를 요청했던 고객에게 약정된 서비스를 제공합니다.
요청이 실패했을 경우
•
응답 코드(result)와 응답 메시지(message) 로 원인을 파악하여 대응합니다.
4. 결제 취소
결제된 거래건을 취소하기 위해서는 파트너에서 페이플로 취소 요청을 해야합니다.
결제 취소 상태는 해외결제 파트너 관리자 결제내역에서 ‘상태’ 값으로 확인할 수 있습니다.
4-1. 취소 프로세스
4-2. 파트너 인증 토큰발급
Partner Server Side
•
파트너는 취소 요청을 보내기 전 파트너 인증 프로세스를 진행해야 합니다.
•
파트너 인증을 위한 토큰 발급은 취소 요청 전 필수로 진행해야 합니다.
발급받은 access_token은 취소 요청 시 필요하며,
토큰의 유효기간(10분)이 지나면 토큰을 다시 발급받으셔야 합니다.
파트너 인증 토큰발급 요청시에는 등록한 IP(White IP)와의 통신만 허용합니다.
이외 IP로 파트너 인증 토큰발급 요청을 할 경우 거부되니 주의해주세요.
Partner Authorization Request Parameters
code는 반드시 영문자+숫자만 포함하여 10자만 입력해야합니다.
Table
Search
Request sample
•
Header 정보
/*
* Request HTTP URL
* TEST : https://demo-api.payple.kr/gpay/oauth/1.0/token
* REAL : https://api.payple.kr/gpay/oauth/1.0/token
*/
Request HTTP URL: "https://demo-api.payple.kr/gpay/oauth/1.0/token"
HTTP Method: POST
Content-Type: application/json
Cache-Control: no-cache
JSON
복사
•
Body(Payload) 값
{
"service_id":"demo",
"service_key":"abcd1234567890",
"code":"as12345678"
}
JSON
복사
Partner Authorization Response Parameters
•
토큰발급 요청이 성공하면 페이플에서 파트너에 다음과 같은 성공 리턴을 드립니다.
Table
Search
Response sample
{
"result": "T0000",
"message": "Process Success",
"code": "as12345678",
"access_token": "eyJhbGciOiJzaGEyNT...",
"token_type": "Bearer",
"payCls": "demo", // 테스트 결제(결제창)인 경우에만 필요
"expires_in": "600"
}
JSON
복사
result= "T0000", message= "Process Success"인 경우 요청 성공으로 판단합니다.
발급받은 access_token은 취소 요청시 Authorization 값으로 필요합니다.
4-3. 결제 취소
Partner Server Side
•
파트너 인증이 완료되면 취소 요청을 합니다.
Cancel Request Parameters
파트너 인증 토큰 발급시 받은 access_token값을 HTTP Authorization Header에 넣어서 요청해주세요.
- 인증 토큰의 유효기간은 10분입니다.
- 한 번의 파트너 인증 토큰 발급으로 유효기간(10분) 이내에 결제를 완료해야 합니다.
페이플에서는 사용자 인증을 OAuth 2.0으로 진행합니다.
Table
Search
Request sample
•
Header 정보
/*
* Request HTTP URL
* TEST : https://demo-api.payple.kr/gpay/cancel
* REAL : https://api.payple.kr/gpay/cancel
*/
Request HTTP URL: "https://demo-api.payple.kr/gpay/cancel"
HTTP Method: POST
Content-Type: application/json
Cache-Control: no-cache
Authorization: Bearer, Access Token
JSON
복사
$arrObHeader = array (
"Authorization: Bearer $paypleToken[access_token]",
"Accept: application/json"
);
PHP
복사
PHP - Header 값 설정 예시
•
Body(Payload) 값
{
"service_id":"demo",
"comments": "테스트상품명",
"service_oid": "test120220608512351",
"pay_id": "6548264741426583803027",
"totalAmount": "0.10",
"currency": "USD",
"resultUrl" : "http://test.shop.com"
}
JSON
복사
Cancel Response Parameters
Table
Search
결제 취소 응답 형식은 아래 Response Sample 형식입니다.
결제 취소 결과로 반환되는 결과는 Depth(info)가 있으니 이 점 참고해주시기 바랍니다.
Response sample
{
"type": "CANCEL",
"result": "A0000",
"message": "처리 성공",
"resultUrl": "http://test.shop.com",
"api_id": "676273618072602",
"api_date": "2022-06-10 16:09:22",
"info": {
"totalAmount": "0.10",
"currency": "USD",
"service_oid": "OID_22072217525616584799763773750",
"submitTimeUtc": "2022-06-10 07:09:22"
},
"serviceDefine": "Service Define Test"
}
JSON
복사
result= "A0000", message= "처리 성공"인 경우 요청 성공으로 판단합니다.
Payple Inc. All rights reserved.