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
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값으로 필요합니다.

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
service_id
Open
"demo"
aN(8)
Y
파트너 ID
service_oid
Open
"test120220608512351"
aN(128)
N
주문번호 - 거래를 특정할 수 있는 고유식별번호로, 항상 유니크하게 지정하여 보내야합니다. - 주문번호를 유니크하게 지정하여 보내지 못하는 경우에는 미지정하는 것을 권장합니다. (미지정하는 경우 페이플에서 임의로 지정)
comments
Open
"테스트상품명"
aAHN(255)
Y
상품명 - comments에 보낸 값이 결제창에 표기됩니다.
billing_key
Open
"MlNCQ0pHMn…"
aNS(128)
Y
빌링키 (카드정보를 암호화 한 키 값)
securityCode
Open
"123"
N(3)
Y
카드 CVC 번호
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"
aAN(6)
N
우편번호 * 보내지 않을 경우, 최초 결제시 입력한 우편번호로 결제요청이 됩니다.
email
Open
"test@payple.kr"
E(250)
N
이메일 주소 * 보내지 않을 경우, 최초 결제시 입력한 이메일로 결제요청이 됩니다.
phoneNumber
Open
"01012345678"
N(11)
N
휴대전화 번호 * 보내지 않을 경우, 최초 결제시 입력한 휴대전화 번호로 결제요청이 됩니다.
resultUrl
Open
"http://test.shop.com"
N
요청 파라미터에 넣어서 보낼 시, 그대로 응답 파라미터로 반환됩니다. - 해당 파라미터(resultUrl)는 별도의 기능은 하지 않으나, 파트너사에서 빌링키 결제 성공시 리다이렉트 하는 등 활용할 수 있는 파라미터 입니다.
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", "country": "US", "administrativeArea": "AZ", "locality": "Seoul", "address1": "302 14 Teheran-ro 34-gil Gangnam-gu", "postalCode": "06220", "email": "test@payple.kr", "phoneNumber": "01012345678", "resultUrl": "http://test.shop.com" }
JSON

Billing Key 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
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", "address1": "302 14 Teheran-ro 34-gil Gangnam-gu"", "locality": "Seoul", "administrativeArea": "AZ", "postalCode": "06220", "country": "US", "email": "test@payple.kr", "phoneNumber": "01012345678", "card_number": "1234-****-****-7890", "submitTimeUtc": "2022-06-10 02:01:16" } }
JSON

6. 결과 처리

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