원스토어 인앱결제 서버 API (API V6)

개요

원스토어 인앱결제 서버 API란 원스토어에서 결제된 인앱 상품의 데이터를 조회하거나 결제 상태를 변경하기 위한 Open API를 말합니다.

해당 API를 사용하기 위해서는 OAuth 인증이 필요합니다.

HOST URL

본 문서에서 사용되는 {host}의 URL은 아래와 같습니다.

원스토어 OAuth

OAuth 개요

원스토어 서버 Open API를 연동하기 위해서는 OAuth 인증이 필요합니다.

원스토어 OAuth v2의 이해
- AccessToken은 원스토어의 Server Open API를 통하여 발급받을 수 있는 값으로 원스토어에서 제공하는 Server Open API 호출시 인증값으로 사용됩니다.
- AccessToken은 기본적으로 3600초의 유효기간이 있으며, 유효기간이 만료 되거나 600초 미만으로 남은 경우에 getAccessToken()을 호출하면 새로운 AccessToken이 발급됩니다.
  - 기존의 AccessToken도 유효기간이 끝날 때까지는 사용이 가능합니다.
  - 다수의 AccessToken이 발행되는 방식이므로 개발사의 서비스 인스턴스 별로 서로 다른 AccessToken을 취득하고 사용할 수 있는 형태가 됩니다.
일반적인 연동 흐름은 다음과 같습니다.
AccessToken을 얻는 과정(1번)은 API 호출 시 인증 오류가 발생했을 때 호출하면 됩니다.

원스토어의 인앱결제 서버 API의 호출을 위해서는 Authorization Bearer 스킴을 사용하며 호출 샘플은 아래와 같습니다.

Authorization 헤더에는 위 예제와 같이 Bearer + 공백 + AccessToken이 대소문자 구분하여 정확히 입력되어야 합니다. Bearer의 값은 getAccessToken()을 호출하여 발급받은 AccessToken 값입니다.

잘못된 예

OAuth API 상세

client_id 및 client_secret 확인

client_id와 client_secret 값은 원스토어 개발자센터에 등록된 App의 In-App 정보 > '인증 및 라이선스' 버튼을 통하여 확인할 수 있습니다.

AccessToken 발급

URI : https://{host}/v6/oauth/token
Method: POST, PUT
Request Parameter: Form 형식
Request Header :
Example
Response Body : JSON 형식
Example :
발급 예시 :
검증(개발) 환경과 상용환경의 AccessToken은 독립적으로 관리되므로, 환경 별로 AccessToken을 분리하여 관리하셔야 합니다.

서버 API 상세

getPurchaseDetails (구매상품 상세조회)

Desc : 구매한 원스토어 관리형 상품의 상세정보를 조회합니다. 구매완료 시 전달받은 원스토어 purchaseToken(구매 토큰)을 이용하여 조회하여야 합니다. 월정액 상품의 purchaseToken으로 조회 시, 조회 실패(NoSuchData) 응답이 전달됩니다.
URI : https://{host}/v6/apps/{packageName}/purchases/inapp/products/{productId}/{purchaseToken}
Method : GET
Request Parameter : Path Variable 형식
- String packageName : API를 호출하는 앱의 패키지 네임 (Data Size : 128)
- String productId : 상품 ID (Data Size : 150)
- String purchaseToken : 구매 토큰 (Data Size : 20)
Request Header:
Example
Request Body : 없음
Response Body : JSON 형식
Example:

getRecurringPurchaseDetails (월정액 상품 구매 상세조회)

Desc : 구매한 원스토어 월정액 상품의 자동결제 상태와 마지막 구매상태의 상세정보를 조회합니다. 구매완료 시 전달받은 원스토어 purchaseToken(구매 토큰)을 이용하여 조회하여야 합니다. 관리형 상품의 purchaseToken으로 조회 시, 조회 실패(NoSuchData) 응답이 전달됩니다.
URI : https://{host}/v6/apps/{packageName}/purchases/auto/products/{productId}/{purchaseToken}
Method : GET
Request Parameter : Path Variable 형식
- String packageName : API를 호출하는 앱의 패키지 네임 (Data Size : 128)
- String productId : 상품 ID (Data Size : 150)
- String purchaseToken : 구매 토큰 (Data Size : 20)
Request Header :
Example :
Request Body : 없음
Response Body : JSON 형식
Example :
고객이 월정액 상품에 대하여 컨텐츠 사용 권한이 있는지 아래의 조건으로 판단이 가능합니다.
- 현재시간이 expiryTime(구매한 상품의 이용종료시간)보다 작거나 같고, lastPurchaseState(마지막에 자동결제된 구매상태)가 0(구매완료) 상태인경우 Ex) expiryTime >= 현재시간 AND lastPurchaseState == 0

acknowledgePurchase (구매상품 확인)

Desc : 구매한 관리형 또는 월정액 상품을 구매확인 상태로 변경한다.
URI : https://{host}/v6/apps/{packageName}/purchases/all/products/{productId}/{purchaseToken}/acknowledge
Method : POST
Request Parameter : Path Variable 형식
- String packageName : API를 호출하는 앱의 패키지 네임 (Data Size : 128)
- String productId : 상품 ID (Data Size : 150)
- String purchaseToken : 구매 토큰 (Data Size : 20)
Request Header :
Example
Request Body : JSON 형식
Example :
Response Body : JSON 형식
API 처리 성공 시 처리완료를 보다 직관적으로 판단할 수 있도록 아래 형식의 응답를 리턴합니다. 단, API 처리 실패 시에는 표준오류응답을 리턴합니다.
Example :
원스토어는 3일 이내에 acknowledgePurchase API가 호출되지 않은 구매 건을 자동으로 취소합니다.
이에 따라 개발사는 반드시 해당 API를 호출해야 하며, SDK API 또는 서버 API를 통해 처리할 수 있습니다.
단, consumePurchase API가 호출된 구매 건은 acknowledge가 되었다고 판단하고 구매 취소를 하지 않습니다.

consumePurchase (구매상품 소비)

Desc : 구매한 관리형 인앱 상품을 소비 상태로 변경한다.
URI : https://{host}/v6/apps/{packageName}/purchases/inapp/products/{productId}/{purchaseToken}/consume
Method : POST
Request Parameter : Path Variable 형식
- String packageName : API를 호출하는 앱의 패키지 네임 (Data Size : 128)
- String productId : 상품 ID (Data Size : 150)
- String purchaseToken : 구매 토큰 (Data Size : 20)
Request Header :
Example
Request Body : JSON 형식
Response Body : JSON 형식
API 처리 성공 시 처리완료를 보다 직관적으로 판단할 수 있도록 아래 형식의 응답를 리턴합니다. 단, API 처리 실패 시에는 표준오류응답을 리턴합니다.
Example :

cancelRecurringPurchase (자동결제 해지요청)

Desc : 월정액 상품의 자동결제 해지를 요청한다.
URI : https://{host}/v6/apps/{packageName}/purchases/auto/products/{productId}/{purchaseToken}/cancel
Method : POST
Request Parameter : Path Variable 형식
- String packageName : API를 호출하는 앱의 패키지 네임 (Data Size : 128)
- String productId : 상품 ID (Data Size : 150)
- String purchaseToken : 구매 토큰 (Data Size : 20)
Request Header :
Example
Request Body : 없음
Response Body : JSON 형식
API 처리 성공 시 처리완료를 보다 직관적으로 판단할 수 있도록 아래 형식의 응답를 리턴합니다. 단, API 처리 실패 시에는 표준오류응답을 리턴합니다.
Example :

reactiveRecurringPurchase (자동결제 해지 취소요청)

Desc : 월정액 상품의 자동결제 해지요청을 취소한다.
URI : https://{host}/v6/apps/{packageName}/purchases/auto/products/{productId}/{purchaseToken}/reactivate
Method : POST
Request Parameter : Path Variable 형식
- String packageName : API를 호출하는 앱의 패키지 네임 (Data Size : 128)
- String productId : 상품 ID (Data Size : 150)
- String purchaseToken : 구매 토큰 (Data Size : 20)
Request Header :
Example
Request Body : 없음
Response Body : JSON 형식
API 처리 성공 시 처리완료를 보다 직관적으로 판단할 수 있도록 아래 형식의 응답를 리턴합니다. 단, API 처리 실패 시에는 표준오류응답을 리턴합니다.
Example :

getVoidedPurchases (구매취소내역 조회)

Desc : 구매취소내역을 조회한다.
URI : https://{host}/v6/apps/{packageName}/voided-purchases
Method : GET
Request Parameter : Path Variable 형식
- String packageName : API를 호출하는 앱의 패키지 네임 (Data Size : 128)
Request Parameter (Optional) : Query String 형식
- String continuationKey : 구매취소 건이 많을 경우 원스토어 서버에서 이 값을 반환합니다. 응답에 continuationKey가 있을 경우, getVoidedPurchases를 다시 호출하면서 continuationKey를 전달하면 추가 구매취소 내역을 전달받을 수 있습니다. (Data Size : 41)
- String startTime : 구매취소일시 검색 시작시간 (milliseconds). 현재시간기준 과거 1개월까지만 설정가능하며 startTime 단독으로 사용할 경우 endTime은 startTime기준 미래 1개월로 설정됩니다. (Data Size : 13)
- String endTime : 구매취소일시 검색 종료시간 (milliseconds). 현재시간보다 클 수 없으며 endTime 단독으로 사용할 경우 startTime은 endTime기준 과거 1개월로 설정됩니다. (Data Size : 13)
- unsigned integer maxResults : 최대조회건수 default 100 (Data Size : 3)
Request Header :
Example
Request Body : 없음
Response Body :
Example :

표준응답규격

표준응답코드

표준오류 응답규격

서버 API에서는 정상적인 응답 외에 오류발생 시, 아래의 Example과 같은 형식의 표준오류응답을 리턴합니다. 아래 내용을 참고하시기 바랍니다.