Search
🚀

[Quick Guide] 해외결제창

본 문서에서는 페이플 해외결제창을 결제부터 취소까지 빠르게 연동해 볼 수 있는 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
Parameter
더 알아보기
Parameter Value
Type (Length)
필수
Reference
"abcd1234567890"
aN(255)
Y
파트너 인증키
"as12345678"
aN(10)
Y
파트너용 토큰 확인 코드
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
Parameter
더 알아보기
Parameter Value
Reference
Type
"T0000"
응답 코드
String
"Process Success"
응답 메시지
String
"as12345678"
파트너용 토큰 확인 코드
String
"eyJhbGciOiJzaGEyNT…"
발행된 Access Token *결제요청시 보내야하는 인증토큰
String
"Bearer" (고정값)
Access Token 유형
String
"600"
Access Token 만료 기간(초)
String
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"인 경우 요청 성공으로 판단합니다.
이외 응답코드(result)는 이곳에서 확인해보세요!
[테스트 서버 유의사항] 테스트 서버(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로 계산하여 최대 길이를 넘지 않게 보내시면 됩니다.
요청 파라미터의 Type 보는 방법에 대해 더 자세히 알아보세요!
Search
Parameter
더 알아보기
Parameter Value
Type (Length)
필수
Reference
"eyJhbGciOiJzaGEyNT..."
-
Y
발급받은 Access Token (파트너 인증 토큰발급 응답값 중 access_token)
"demo"
aN(8)
Y
파트너 ID
"test120220608512351"
aN(128)
N
주문번호 - 거래를 특정할 수 있는 고유식별번호로, 항상 유니크하게 지정하여 보내야합니다. - 주문번호를 유니크하게 지정하여 보내지 못하는 경우에는 미지정하는 것을 권장합니다. (미지정하는 경우 페이플에서 임의로 지정)
"테스트상품명"
aAHN(200)
Y
상품명 - comments에 보낸 값이 결제창에 표기됩니다.
"0.10"
N
Y
결제 요청금액 - 파트너 관리자에 설정된 최소 금액과 최대 금액 사이의 값만 결제가 가능합니다. - 결제 요청 금액의 소수점 둘째 자리 미만은 버림으로 처리됩니다. (소수점 둘째 자리까지 허용) *통화(currency)가 원화(KRW)인 경우, 정수만 허용됩니다.
"USD"
A(3)
Y
통화
"Gildong"
aAHN(25)
N
카드소유주 이름
"Hong"
aAHN(25)
N
카드소유주 성
"test@payple.kr"
E(250)
N
이메일 주소
"http://test.shop.com"
Y
결제결과 반환(Return) URL - 해당 URL로 결제 완료 후 결과를 POST로 전송합니다. - 결제결과의 정상적인 수신을 위해 유효한 URL을 보내주세요.
["Y" | ""]
A(1)
N
결제창 호출 다이렉트 여부 - 결제창 호출방식을 다이렉트로 할 경우에만 대문자 Y를 보내야합니다.
"Service Define Test"
aAHNS(2048)
N
사용자 정의 파라미터 - 파트너사에서 요청한 값이 결제완료 후 그대로 반환됩니다. *KEY-VALUE 형태가 아닌 String 형식으로 보내주세요.
["demo" | ""]
테스트시
Y
테스트 결제 요청시에만 반드시 보내주세요 - 테스트 결제시 payCls를 demo로 설정하여 보내주시기 바랍니다.
결제요청 파라미터 중 필수가 아닌 선택 파라미터를 보내시면 결제창에 미리 해당 값을 입력하는 기능을 수행합니다. 고객이 입력해야하는 필드값을 줄어들게 하는 효과가 있습니다. (단, 결제창에 필드값만 해당 - 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

Search
Parameter
더 알아보기
Parameter Value
Reference
Type
"PAYMENT"
요청 종류 - 결제: PAYMENT - 취소: CANCEL
String
"A0000"
응답 코드
String
"처리 성공"
응답 메시지
String
"http://test.shop.com"
결제결과 반환(Return) URL
String
"6548264741426583803027"
결제결과 고유키
String
"2022-06-10 11:01:17"
결제 시간 - 페이플 서버기준: GMT +9 *해외결제 사용자의 기준이 되는 시간은 submitTimeUtc이니 참고해주시기 바랍니다.
String
"test120220608512351"
주문번호
String
"테스트상품명"
상품명
String
"card"
결제수단
String
"1234-****-****-7890"
카드번호 (일부 마스킹 처리)
String
"0.10"
결제 요청금액
String
"USD"
통화
String
"Gildong"
카드소유주 이름
String
"Hong"
카드소유주 성
String
"test@payple.kr"
이메일 주소
String
"MlNCQ0pHMn…"
빌링키 (카드정보를 암호화 한 키 값)
String
"2022-06-10 02:01:16"
결제 시간 - 사용자 입장에서 기준이 되는 결제시간: GMT
String
"Service Define Test"
사용자 정의 파라미터
String
결제창 결제 완료 후 수신하는 결제 응답은 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
파트너는 API 요청을 보내기 전 파트너 인증 프로세스를 진행해야 합니다.
파트너 인증을 위한 토큰 발급은 API 요청 전 필수로 진행해야 합니다.
발급받은 access_token은 API 요청 시 필요하며, 토큰의 유효기간(10분)이 지나면 토큰을 다시 발급받으셔야 합니다.
파트너 인증 토큰발급 요청시에는 등록한 IP(White IP)와의 통신만 허용합니다. 이외 IP로 파트너 인증 토큰발급 요청을 할 경우 거부되니 주의해주세요.

Partner Authorization Request Parameters

code는 반드시 영문자+숫자만 포함하여 10자만 입력해야합니다.
Table
Search
Parameter
더 알아보기
Parameter Value
Type (Length)
필수
Reference
"demo"
aN(8)
Y
파트너 ID
"abcd1234567890"
aN(255)
Y
파트너 인증키
"as12345678"
aN(10)
Y
파트너용 토큰 확인 코드
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
Parameter
더 알아보기
Parameter Value
Reference
Type
"T0000"
응답 코드
String
"Process Success"
응답 메시지
String
"as12345678"
파트너용 토큰 확인 코드
String
"eyJhbGciOiJzaGEyNT…"
발행된 Access Token *결제요청시 보내야하는 인증토큰
String
"Bearer" (고정값)
Access Token 유형
String
"600"
Access Token 만료 기간(초)
String
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"인 경우 요청 성공으로 판단합니다.
이외 응답코드(result)는 이곳에서 확인해보세요!
발급받은 access_token은 취소 요청시 Authorization 값으로 필요합니다.

4-3. 결제 취소

Partner Server Side
파트너 인증이 완료되면 취소 요청을 합니다.

Cancel Request Parameters

파트너 인증 토큰 발급시 받은 access_token값을 HTTP Authorization Header에 넣어서 요청해주세요. - 인증 토큰의 유효기간은 10분입니다. - 한 번의 파트너 인증 토큰 발급으로 유효기간(10분) 이내에 결제를 완료해야 합니다.
페이플에서는 사용자 인증을 OAuth 2.0으로 진행합니다.
Table
Search
Parameter
더 알아보기
Parameter Value
Type (Length)
필수
Reference
"demo"
aN(8)
Y
파트너 ID
"테스트상품명"
aAHN(200)
Y
상품명
"test120220608512351"
aN(128)
Y
주문번호
"6548264741426583803027"
Y
취소할 결제건의 api_id * 결제 결과로 받은 응답값인 결제결과 고유키인 api_id를 보내야합니다.
"0.10"
N
Y
결제 취소 요청금액 - 취소할 결제건의 실 결제금액보다 작거나 같은 금액을 보내야합니다.
"USD"
A(3)
Y
통화 - 취소할 결제건의 통화로 보내야합니다.
"http://test.shop.com"
N
요청 파라미터에 넣어서 보낼 시, 그대로 응답 파라미터로 반환됩니다. - 해당 파라미터(resultUrl)는 별도의 기능은 하지 않으나, 파트너사에서 취소 성공시 리다이렉트 하는 등 활용할 수 있는 파라미터 입니다.
"Service Define Test"
aAHNS(2048)
N
사용자 정의 파라미터 - 파트너사에서 요청한 값이 결제완료 후 그대로 반환됩니다. *KEY-VALUE 형태가 아닌 String 형식으로 보내주세요.
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
Parameter
더 알아보기
Parameter Value
Reference
Type
"CANCEL"
요청 종류 - 결제: PAYMENT - 취소: CANCEL
String
"A0000"
응답 코드
String
"처리 성공"
응답 메시지
String
"http://test.shop.com"
취소 요청시 보낸 값 그대로 반환
String
"676273618072602"
결제취소 고유키
String
"2022-06-10 16:09:22"
결제취소 요청 일자
String
"0.10"
결제취소 요청 금액
String
"USD"
결제취소 통화
String
"2022-06-10 07:09:22"
"Service Define Test"
사용자 정의 파라미터
String
결제 취소 응답 형식은 아래 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= "처리 성공"인 경우 요청 성공으로 판단합니다.
이외 응답코드(result)는 이곳에서 확인해보세요!
Payple Inc. All rights reserved.