Search

[해외] 빌링키 결제 (REST API)

본 문서에서는 페이플 빌링키 결제 가이드를 안내합니다.

1. 빌링키 결제(REST)란?

고객이 최초 1회 카드 결제를 완료하면, 이후 결제시 카드 정보 입력 없이
등록된 카드 정보를 암호화 한 키 값인 빌링키로 결제하는 방식입니다.
페이플에서 제공하는 빌링키 결제로 파트너에서는 정기결제를 구현할 수 있습니다. 결제가 필요할 때마다 파트너가 발급된 빌링키(billing_key)로 실시간으로 REST 결제요청을 페이플로 보내어 결제를 하는 방식입니다.
빌링키 결제 REST 방식파트너 서버와 페이플 서버간 통신으로 결제요청과 응답이 이루어지는 방식입니다.
결제창에서 이루어지는 것이 아닌, 서버단에서 진행되는 REST 방식이니 참고해주세요.

2. 빌링키 결제(REST) 프로세스 개요

빌링키 결제의 프로세스는 다음과 같이 진행됩니다.
빌링키 결제필수로 등록하거나 결제한 카드 정보(빌링키)가 있어야합니다. 카드 정보를 암호화 한 값인 빌링키는 결제창에서 결제 후 응답 파라미터로 반환되며, 파트너에서는 결제하려는 카드의 빌링키를 식별하여 저장해두고 결제를 요청해야합니다. ※ 빌링키는 결제창에서 최초 결제를 1회 해야만 반환되는 점 참고해주세요!
해외카드 결제창 연동가이드이곳에서 확인해보세요!

3. White IP 등록

페이플 해외카드 결제 - 운영(REAL)에서는 등록되어 있는 IP와의 통신만 허용하고 있습니다.
테스트(demo)는 별도의 White IP 등록없이 해외카드 결제를 위한 통신이 가능합니다.
White IP 등록은 파트너 인증 토큰발급을 위해 필요한 절차이며, 파트너 인증 토큰 발급 요청시에는 등록한 IP로 통신해야합니다.

4. 파트너 인증 토큰발급

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)는 이곳에서 확인해보세요!
발급받은 access_token은 결제 요청시 Authorization값으로 필요합니다.

5. 빌링키 결제요청

Partner Server Side
파트너 인증이 완료되면 빌링키 결제요청을 합니다.

Billing Key Payment Request Parameters

파트너 인증 토큰 발급시 받은 access_token값을 HTTP Authorization Header에 넣어서 요청해주세요. - 인증 토큰의 유효기간은 10분입니다. - 한 번의 파트너 인증 토큰 발급으로 유효기간(10분) 이내에 결제를 완료해야 합니다.
페이플에서는 사용자 인증을 OAuth 2.0으로 진행합니다.
빌링키 결제 요청시 결제자 정보와 청구지 정보는 선택 파라미터이지만, 해당 정보를 보내지 않는다면 결제 요청시 해당 빌링키에 저장된 이전 결제자/청구지 정보가 요청 정보로 보내지기 때문에, 새로 정보를 입력하여 요청 하는 것을 권장합니다.
요청 파라미터의 길이(Length)는 Byte 기준입니다. - 한글의 경우, 1글자당 3Byte로 계산하여 최대 길이를 넘지 않게 보내시면 됩니다.
요청 파라미터의 Type 보는 방법에 대해 더 자세히 알아보세요!
Table
Search
Parameter
더 알아보기
Parameter Value
Type (Length)
필수
Reference
"demo"
aN(8)
Y
파트너 ID
"test120220608512351"
aN(128)
N
주문번호 - 거래를 특정할 수 있는 고유식별번호로, 항상 유니크하게 지정하여 보내야합니다. - 주문번호를 유니크하게 지정하여 보내지 못하는 경우에는 미지정하는 것을 권장합니다. (미지정하는 경우 페이플에서 임의로 지정)
"테스트상품명"
aAHN(200)
Y
상품명 - comments에 보낸 값이 결제창에 표기됩니다.
"MlNCQ0pHMn…"
aNS(128)
Y
빌링키 (카드정보를 암호화 한 키 값)
"123"
N(3)
Y
카드 CVC 번호
"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"
N
요청 파라미터에 넣어서 보낼 시, 그대로 응답 파라미터로 반환됩니다. - 해당 파라미터(resultUrl)는 별도의 기능은 하지 않으나, 파트너사에서 빌링키 결제 성공시 리다이렉트 하는 등 활용할 수 있는 파라미터 입니다.
"Service Define Test"
aAHNS(2048)
N
사용자 정의 파라미터 - 파트너사에서 요청한 값이 결제완료 후 그대로 반환됩니다. *KEY-VALUE 형태가 아닌 String 형식으로 보내주세요.
Request sample
Header 정보
/* * Request HTTP URL * TEST : https://demo-api.payple.kr/gpay/billingKey * REAL : https://api.payple.kr/gpay/billingKey */ Request HTTP URL: "https://demo-api.payple.kr/gpay/billingKey" 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", "service_oid": "test120220608512351", "comments": "테스트상품명", "billing_key": "MlNCQ0pHMn…", "totalAmount": "0.10", "currency": "USD", "firstName": "Gildong", "lastName": "Hong", "email": "test@payple.kr", "resultUrl": "http://test.shop.com" }
JSON
복사

Billing Key Payment Response Parameters

Table
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
빌링키 결제결과 형식은 아래 Response Sample 형식입니다.
결제창에서 결제완료 후 반환되는 결제결과는 Depth가 없지만,
빌링키 결제결과로 반환되는 결과는 Depth(info)가 있으니, 이 점 참고해주시기 바랍니다.
Response sample
{ "type": "PAYMENT", "result": "A0000", "message": "처리 성공", "resultUrl": "http://test.shop.com", "api_id": "6548264741426583803027", "api_date": "2022-06-10 11:01:17", "info": { "service_oid": "test120220608512351", "comments": "테스트상품명", "pay_type": "card", "billing_key": "MlNCQ0pHMn...", "totalAmount": "0.10", "currency": "USD", "firstName": "Gildong", "lastName": "Hong", "email": "test@payple.kr", "card_number": "1234-****-****-7890", "submitTimeUtc": "2022-06-10 02:01:16" }, "serviceDefine": "Service Define Test" }
JSON
복사

6. 결과 처리

Partner Server Side
파트너사에서 페이플로부터 받은 결제 결과(Response)를 처리합니다.
결제 성공여부는 결제 결과 파라미터인 응답코드(result)를 보고 판단합니다.
result = "A0000" 인 경우 요청 성공으로 판단합니다.
이외 코드인 경우 요청 실패로 판단합니다.
응답코드이곳에서 확인해보세요!
Payple Inc. All rights reserved.