Search
✂️

빌링키 삭제/차단/해제 API

본 문서에서는 페이플 빌링키 삭제/차단/해제 가이드를 안내합니다.

1. 정의

•
빌링키 삭제란 발급된 빌링키가 더 이상 사용되지 않도록 삭제(해지)하는 기능입니다.
◦
결제자가 더 이상 해당 카드의 이용을 원치 않는 경우 빌링키 삭제 API를 활용할 수 있습니다.
•
빌링키 차단/해제란 발급된 빌링키로 결제되지 않도록 차단 또는 해제하는 기능입니다.
◦
결제자가 등록한 카드의 이용을 임시로 중단하거나 비정상적인 결제 활동이 의심되는 경우 빌링키 차단 API를 활용할 수 있습니다.

2. 프로세스 개요

빌링키 삭제/차단/해제의 프로세스는 다음과 같이 진행됩니다.

3. 파트너 인증 토큰발급

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
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)는 이곳에서 확인해보세요!

4. 빌링키 삭제 요청

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

Billing Key Revoke Request Parameters

파트너 인증 토큰 발급시 받은 access_token값을 HTTP Authorization Header에 넣어서 요청해주세요. - 인증 토큰의 유효기간은 10분입니다. - 한 번의 파트너 인증 토큰 발급으로 유효기간(10분) 이내에 결제를 완료해야 합니다.
페이플에서는 사용자 인증을 OAuth 2.0으로 진행합니다.
Search
Parameter
더 알아보기
Parameter Value
Type (Length)
필수
Reference
service_id
Open
"demo"
aN(8)
Y
파트너 ID
billing_key
Open
"MlNCQ0pHMn…"
aN(128)
Y
빌링키 (카드정보를 암호화 한 키 값)
Request sample
•
Header 정보
/* * Request HTTP URL * TEST : https://demo-api.payple.kr/gpay/billingkey/revoke * REAL : https://api.payple.kr/gpay/billingkey/revoke */ Request HTTP URL: "https://demo-api.payple.kr/gpay/billingkey/revoke" 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", "billing_key": "MlNCQ0pHMn…" }
JSON
복사

Billing Key Revoke Response Parameters

Search
Parameter
더 알아보기
Parameter Value
Reference
Type
type
Open
"BILLKEY"
요청 업부 구분
String
result
Open
"A0000"
응답 코드
String
message
Open
"처리 성공"
응답 메시지
String
billing_key
Open
"MlNCQ0pHMn…"
빌링키 (카드정보를 암호화 한 키 값)
String
api_date
Open
"2023-12-19 10:00:00"
빌링키 삭제 일시 - 페이플 서버기준: GMT +9 * 해외결제 사용자의 기준이 되는 시간은 submitTimeUtc이니 참고해주시기 바랍니다.
String
submitTimeUtc
Open
"2023-12-19 01:00:00"
빌링키 삭제 일시 - 사용자 입장에서 기준이 되는 결제시간: GMT
String
빌링키 삭제 응답 형식은 아래 Response Sample 형식입니다.
Response sample
{ "type": "BILLKEY", "result": "A0000", "message": "Processing Success", "billing_key": "MlNCQ0pHMn…", "api_date": "2023-12-19 10:00:00", "submitTimeUtc": "2023-12-19 01:00:00" }
JSON
복사
result= "A0000", message= "Processing Success"인 경우 요청 성공으로 판단합니다.
이외 응답코드(result)는 이곳에서 확인해보세요!

5. 빌링키 차단 요청

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

Billing Key Block Request Parameters

파트너 인증 토큰 발급시 받은 access_token값을 HTTP Authorization Header에 넣어서 요청해주세요. - 인증 토큰의 유효기간은 10분입니다. - 한 번의 파트너 인증 토큰 발급으로 유효기간(10분) 이내에 결제를 완료해야 합니다.
페이플에서는 사용자 인증을 OAuth 2.0으로 진행합니다.
Search
Parameter
더 알아보기
Parameter Value
Type (Length)
필수
Reference
service_id
Open
"demo"
aN(8)
Y
파트너 ID
billing_key
Open
"MlNCQ0pHMn…"
aN(128)
Y
빌링키 (카드정보를 암호화 한 키 값)
Request sample
•
Header 정보
/* * Request HTTP URL * TEST : https://demo-api.payple.kr/gpay/billingkey/block * REAL : https://api.payple.kr/gpay/billingkey/block */ Request HTTP URL: "https://demo-api.payple.kr/gpay/billingkey/block" 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", "billing_key": "MlNCQ0pHMn…" }
JSON
복사

Billing Key Block Response Parameters

Search
Parameter
더 알아보기
Parameter Value
Reference
Type
type
Open
"BILLKEY"
요청 업부 구분
String
result
Open
"A0000"
응답 코드
String
message
Open
"처리 성공"
응답 메시지
String
billing_key
Open
"MlNCQ0pHMn…"
빌링키 (카드정보를 암호화 한 키 값)
String
api_date
Open
"2023-12-19 10:00:00"
빌링키 차단 일시 - 페이플 서버기준: GMT +9 * 해외결제 사용자의 기준이 되는 시간은 submitTimeUtc이니 참고해주시기 바랍니다.
String
submitTimeUtc
Open
"2023-12-19 01:00:00"
빌링키 차단 일시 - 사용자 입장에서 기준이 되는 결제시간: GMT
String
빌링키 차단 응답 형식은 아래 Response Sample 형식입니다.
Response sample
{ "type": "BILLKEY", "result": "A0000", "message": "Processing Success", "billing_key": "MlNCQ0pHMn…", "api_date": "2023-12-19 10:00:00", "submitTimeUtc": "2023-12-19 01:00:00" }
JSON
복사
result= "A0000", message= "Processing Success"인 경우 요청 성공으로 판단합니다.
이외 응답코드(result)는 이곳에서 확인해보세요!

6. 빌링키 차단 해제 요청

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

Billing Key Unblock Request Parameters

파트너 인증 토큰 발급시 받은 access_token값을 HTTP Authorization Header에 넣어서 요청해주세요. - 인증 토큰의 유효기간은 10분입니다. - 한 번의 파트너 인증 토큰 발급으로 유효기간(10분) 이내에 결제를 완료해야 합니다.
페이플에서는 사용자 인증을 OAuth 2.0으로 진행합니다.
Search
Parameter
더 알아보기
Parameter Value
Type (Length)
필수
Reference
service_id
Open
"demo"
aN(8)
Y
파트너 ID
billing_key
Open
"MlNCQ0pHMn…"
aN(128)
Y
빌링키 (카드정보를 암호화 한 키 값)
Request sample
•
Header 정보
/* * Request HTTP URL * TEST : https://demo-api.payple.kr/gpay/billingkey/unblock * REAL : https://api.payple.kr/gpay/billingkey/unblock */ Request HTTP URL: "https://demo-api.payple.kr/gpay/billingkey/unblock" 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", "billing_key": "MlNCQ0pHMn…" }
JSON
복사

Billing Key Unblock Response Parameters

Search
Parameter
더 알아보기
Parameter Value
Reference
Type
type
Open
"BILLKEY"
요청 업부 구분
String
result
Open
"A0000"
응답 코드
String
message
Open
"처리 성공"
응답 메시지
String
billing_key
Open
"MlNCQ0pHMn…"
빌링키 (카드정보를 암호화 한 키 값)
String
api_date
Open
"2023-12-19 10:00:00"
빌링키 차단해제 일시 - 페이플 서버기준: GMT +9 * 해외결제 사용자의 기준이 되는 시간은 submitTimeUtc이니 참고해주시기 바랍니다.
String
submitTimeUtc
Open
"2023-12-19 01:00:00"
빌링키 차단해제 일시 - 사용자 입장에서 기준이 되는 결제시간: GMT
String
빌링키 해제 응답 형식은 아래 Response Sample 형식입니다.
Response sample
{ "type": "BILLKEY", "result": "A0000", "message": "Processing Success", "billing_key": "MlNCQ0pHMn…", "api_date": "2023-12-19 10:00:00", "submitTimeUtc": "2023-12-19 01:00:00" }
JSON
복사
result= "A0000", message= "Processing Success"인 경우 요청 성공으로 판단합니다.
이외 응답코드(result)는 이곳에서 확인해보세요!
Payple Inc. All rights reserved.