본 문서에서는 페이플 빌링키 결제 가이드를 안내합니다.
1. 빌링키 결제(REST)란?
•
고객이 최초 1회 카드 결제를 완료하면, 이후 결제시 카드 정보 입력 없이
등록된 카드 정보를 암호화 한 키 값인 빌링키로 결제하는 방식입니다.
페이플에서 제공하는 빌링키 결제로 파트너에서는 정기결제를 구현할 수 있습니다.
결제가 필요할 때마다 파트너가 발급된 빌링키(billing_key)로 실시간으로
REST 결제요청을 페이플로 보내어 결제를 하는 방식입니다.
)로 실시간으로
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
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값으로 필요합니다.
5. 빌링키 결제요청
Partner Server Side
•
파트너 인증이 완료되면 빌링키 결제요청을 합니다.
Billing Key Payment Request Parameters
파트너 인증 토큰 발급시 받은 access_token값을 HTTP Authorization Header에 넣어서 요청해주세요.
- 인증 토큰의 유효기간은 10분입니다.
- 한 번의 파트너 인증 토큰 발급으로 유효기간(10분) 이내에 결제를 완료해야 합니다.
페이플에서는 사용자 인증을 OAuth 2.0으로 진행합니다.
빌링키 결제 요청시 결제자 정보와 청구지 정보는 선택 파라미터이지만,
해당 정보를 보내지 않는다면 결제 요청시 해당 빌링키에 저장된 이전 결제자/청구지 정보가 요청 정보로 보내지기 때문에, 새로 정보를 입력하여 요청 하는 것을 권장합니다.
요청 파라미터의 길이(Length)는 Byte 기준입니다.
- 한글의 경우, 1글자당 3Byte로 계산하여 최대 길이를 넘지 않게 보내시면 됩니다.
Table
Search
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
빌링키 결제결과 형식은 아래 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.