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
service_key
Open
"abcd1234567890"
aN(255)
Y
파트너 인증키
code
Open
"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
result
Open
"T0000"
응답 코드
String
message
Open
"Process Success"
응답 메시지
String
code
Open
"as12345678"
파트너용 토큰 확인 코드
String
access_token
Open
"eyJhbGciOiJzaGEyNT…"
발행된 Access Token *결제요청시 보내야하는 인증토큰
String
token_type
Open
"Bearer" (고정값)
Access Token 유형
String
expires_in
Open
"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

파트너 인증 토큰 발급 후 결제창을 호출할 수 있는 스크립트를 추가하여 페이플에 요청합니다.
// 서버별 페이플 해외카드 결제 스크립트 추가 <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)
JavaScript
페이플 해외카드 결제 스크립트를 추가한 후 결제요청 파라미터를 Object 객체에 담아 paypleGpayPaymentRequest(Object)를 호출하면 결제창이 열립니다.
결제창 요청 예시
// 페이플 해외카드 결제창 호출 function requsetGlobalPay() { // obj에 결제요청 파라미터 저장 let obj = new Object(); /* 중략 */ // 결제요청 함수 호출 paypleGpayPaymentRequest(obj); }
JavaScript
JavaScript

Payment Request Parameters

파트너 인증 토큰 발급시 받은 access_token값을 Authorization에 넣어서 요청해주세요. - 인증 토큰의 유효기간은 10분입니다. - 한 번의 파트너 인증 토큰 발급으로 유효기간(10분) 이내에 결제를 완료해야 합니다.
[테스트 결제 유의사항] 테스트 서버(demo-api.payple.kr)로 파트너 인증 토큰발급 요청을 보내신 경우에는 파트너 인증 토큰 발급시 받은 payCls값을 요청 파라미터로 함께 보내셔야 합니다. 테스트 결제시에 payCls값을 보내지 않으면, 테스트(TEST)서버가 아닌 운영(LIVE)서버로 결제 요청이 보내집니다. 같은 맥락으로, 실제 서비스 결제(LIVE)를 요청할 때에는 payCls를 보내면 안됩니다. 테스트와 운영 결제 요청을 반드시 구분해주세요!
요청 파라미터의 길이(Length)는 Byte 기준입니다. - 한글의 경우, 1글자당 3Byte로 계산하여 최대 길이를 넘지 않게 보내시면 됩니다.
요청 파라미터의 Type 보는 방법에 대해 더 자세히 알아보세요!
Table
Search
Parameter
더 알아보기
Parameter Value
Type (Length)
필수
Reference
Authorization
Open
"eyJhbGciOiJzaGEyNT..."
-
Y
발급받은 Access Token (파트너 인증 토큰발급 응답값 중 access_token)
service_id
Open
"demo"
aN(8)
Y
파트너 ID
service_oid
Open
"test120220608512351"
aN(128)
N
주문번호 - 거래를 특정할 수 있는 고유식별번호로, 항상 유니크하게 지정하여 보내야합니다. - 주문번호를 유니크하게 지정하여 보내지 못하는 경우에는 미지정하는 것을 권장합니다. (미지정하는 경우 페이플에서 임의로 지정)
comments
Open
"테스트상품명"
aAHN(255)
Y
상품명 - comments에 보낸 값이 결제창에 표기됩니다.
totalAmount
Open
"0.10"
N
Y
결제 요청금액 - 파트너 관리자에 설정된 최소 금액과 최대 금액 사이의 값만 결제가 가능합니다. *통화(currency)가 원화(KRW)인 경우, 정수만 허용됩니다.
currency
Open
"USD"
A(3)
Y
통화
firstName
Open
"Gildong"
aAHN(25)
N
카드소유주 이름
lastName
Open
"Hong"
aAHN(25)
N
카드소유주 성
country
Open
"US"
A(2)
N
국가 - 정확한 국가 코드(영어 대문자 2글자)로 보내야하며, 없는 코드일 경우, 결제창에는 국가가 선택되지 않은채로 보여집니다. - 국가코드는 보내지 않으셔도 결제창에서 선택할 수 있습니다. - 국가코드는 이곳에서 확인할 수 있습니다.
administrativeArea
Open
"AZ"
A(2)
N
도/시 - 국가가 미국(US), 혹은 캐나다(CA)인 경우에만 필요한 값으로, 이외 국가의 경우에는 필요하지 않은 값입니다. - 도/시 코드를 모를경우, 보내지 않으셔도 결제창에서 선택할 수 있습니다.
locality
Open
"Seoul"
aNS(32)
N
시/구/군 - 특수문자는 space(공백)와 - . _ 만 가능합니다.
address1
Open
"302 14 Teheran-ro 34-gil Gangnam-gu"
aNS(40)
N
도로명 - 특수문자는 space(공백)와 - . _ 만 가능합니다.
postalCode
Open
"06220"
aN(6)
N
우편번호
email
Open
"test@payple.kr"
E(250)
N
이메일 주소
phoneNumber
Open
"01012345678"
N(11)
N
휴대전화 번호
resultUrl
Open
"http://test.shop.com"
Y
결제결과 반환(Return) URL - 해당 URL로 결제 완료 후 결과를 POST로 전송합니다. - 결제결과의 정상적인 수신을 위해 유효한 URL을 보내주세요.
isDirect
Open
["Y" | ""]
A(1)
N
결제창 호출 다이렉트 여부 - 결제창 호출방식을 다이렉트로 할 경우에만 대문자 Y를 보내야합니다.
payCls
Open
["demo" | ""]
테스트시
Y
테스트 결제 요청시에만 반드시 보내주세요 - 테스트 결제시 payCls를 demo로 설정하여 보내주시기 바랍니다.
결제요청 파라미터 중 필수가 아닌 선택 파라미터를 보내시면 결제창에 미리 해당 값을 입력하는 기능을 수행합니다. 고객이 입력해야하는 필드값을 줄어들게 하는 효과가 있습니다. (단, 결제창에 필드값만 해당 - service_oid , isDirect 제외)
국가(country) 코드는 이곳에서 확인해보세요!
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.country = "US"; obj.address1 = "302 14 Teheran-ro 34-gil Gangnam-gu"; obj.locality = "Seoul"; obj.administrativeArea = "AZ"; obj.postalCode = "06220"; obj.email = "test@payple.kr"; obj.phoneNumber = "01012345678"; 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
Parameter
더 알아보기
Parameter Value
Reference
Type
type
Open
"PAYMENT"
요청 종류 - 결제: PAYMENT - 취소: CANCEL
String
result
Open
"A0000"
응답 코드
String
message
Open
"처리 성공"
응답 메시지
String
resultUrl
Open
"http://test.shop.com"
결제결과 반환(Return) URL
String
api_id
Open
"6548264741426583803027"
결제결과 고유키
String
api_date
Open
"2022-06-10 11:01:17"
결제 시간 - 페이플 서버기준: GMT +9 *해외결제 사용자의 기준이 되는 시간은 submitTimeUtc이니 참고해주시기 바랍니다.
String
service_oid
Open
"test120220608512351"
주문번호
String
comments
Open
"테스트상품명"
상품명
String
pay_type
Open
"card"
결제수단
String
card_number
Open
"1234-****-****-7890"
카드번호 (일부 마스킹 처리)
String
totalAmount
Open
"0.10"
결제 요청금액
String
currency
Open
"USD"
통화
String
firstName
Open
"Gildong"
카드소유주 이름
String
lastName
Open
"Hong"
카드소유주 성
String
address1
Open
"302 14 Teheran-ro 34-gil Gangnam-gu"
도로명
String
locality
Open
"Seoul"
시/구/군
String
country
Open
"US"
국가
String
administrativeArea
Open
"AZ"
도/시 - 국가가 미국(US), 혹은 캐나다(CA)인 경우에는 선택한 도/시 코드가 반환됩니다.
String
postalCode
Open
"06220"
우편번호
String
email
Open
"test@payple.kr"
이메일 주소
String
phoneNumber
Open
"01012345678"
휴대전화 번호
String
billing_key
Open
"MlNCQ0pHMn…"
빌링키 (카드정보를 암호화 한 키 값)
String
submitTimeUtc
Open
"2022-06-10 02:01:16"
결제 시간 - 사용자 입장에서 기준이 되는 결제시간: GMT
String
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. 결제 취소

결제된 거래건을 취소하기 위해서는 파트너에서 페이플로 취소 요청을 해야합니다.
결제 취소는 결제 승인 기준 24시간 내에 취소 요청 보내면 즉시 취소가 되지만, 그 이후에 요청하는 건은 결제 취소 요청을 보낸 익일에 실제 결제 취소가 수행됩니다.
결제 취소 상태는 해외결제 파트너 관리자 결제내역에서 ‘상태’ 값으로 확인할 수 있습니다.

4-1. 취소 프로세스

4-2. 파트너 인증 토큰발급

Partner Server Side
파트너는 취소 요청을 보내기 전 파트너 인증 프로세스를 진행해야 합니다.
파트너 인증을 위한 토큰 발급은 취소 요청 전 필수로 진행해야 합니다.
발급받은 access_token은 취소 요청 시 필요하며, 토큰의 유효기간(10분)이 지나면 토큰을 다시 발급받으셔야 합니다.
파트너 인증 토큰발급 요청시에는 등록한 IP(White IP)와의 통신만 허용합니다. 이외 IP로 파트너 인증 토큰발급 요청을 할 경우 거부되니 주의해주세요.

Partner Authorization Request Parameters

code는 반드시 영문자+숫자만 포함하여 10자만 입력해야합니다.
Table
Search
Parameter
더 알아보기
Parameter Value
Type (Length)
필수
Reference
service_id
Open
"demo"
aN(8)
Y
파트너 ID
service_key
Open
"abcd1234567890"
aN(255)
Y
파트너 인증키
code
Open
"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
result
Open
"T0000"
응답 코드
String
message
Open
"Process Success"
응답 메시지
String
code
Open
"as12345678"
파트너용 토큰 확인 코드
String
access_token
Open
"eyJhbGciOiJzaGEyNT…"
발행된 Access Token *결제요청시 보내야하는 인증토큰
String
token_type
Open
"Bearer" (고정값)
Access Token 유형
String
expires_in
Open
"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
service_id
Open
"demo"
aN(8)
Y
파트너 ID
comments
Open
"테스트상품명"
aAHN(255)
Y
상품명
service_oid
Open
"test120220608512351"
aN(128)
Y
주문번호
pay_id
Open
"6548264741426583803027"
Y
취소할 결제건의 api_id * 결제 결과로 받은 응답값인 결제결과 고유키인 api_id를 보내야합니다.
totalAmount
Open
"0.10"
N
Y
결제 취소 요청금액 - 취소할 결제건의 실 결제금액보다 작거나 같은 금액을 보내야합니다.
currency
Open
"USD"
A(3)
Y
통화 - 취소할 결제건의 통화로 보내야합니다.
resultUrl
Open
"http://test.shop.com"
N
요청 파라미터에 넣어서 보낼 시, 그대로 응답 파라미터로 반환됩니다. - 해당 파라미터(resultUrl)는 별도의 기능은 하지 않으나, 파트너사에서 취소 성공시 리다이렉트 하는 등 활용할 수 있는 파라미터 입니다.
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
type
Open
"CANCEL"
요청 종류 - 결제: PAYMENT - 취소: CANCEL
String
result
Open
"A0000"
응답 코드
String
message
Open
"처리 성공"
응답 메시지
String
resultUrl
Open
"http://test.shop.com"
취소 요청시 보낸 값 그대로 반환
String
api_date
Open
"2022-06-10 16:09:22"
결제취소 요청 일자
String
totalAmount
Open
"0.10"
결제취소 요청 금액
String
currency
Open
"USD"
결제취소 통화
String
submitTimeUtc
Open
"2022-06-10 07:09:22"
Response sample
{ "type": "CANCEL", "result": "A0000", "message": "처리 성공", "resultUrl": "http://test.shop.com", "api_date": "2022-06-10 16:09:22", "info": { "service_oid": "OID_22072217525616584799763773750", "totalAmount": "0.10", "currency": "USD", "submitTimeUtc": "2022-06-10 07:09:22" } }
JSON
result= "A0000", message= "처리 성공"인 경우 요청 성공으로 판단합니다.
이외 응답코드(result)는 이곳에서 확인해보세요!
Payple Inc. All rights reserved.