# 06. 원스토어 인앱결제 서버 API (API V7) ## **개요** 원스토어 인앱결제 서버 API란 원스토어에서 결제된 인앱 상품의 데이터를 조회하거나 결제 상태를 변경하기 위한 Open API를 말합니다. 해당 API를 사용하기 위해서는 OAuth 인증이 필요합니다. ### **HOST URL** 본 문서에서 사용되는 Host Domain은 아래와 같습니다. | 원스토어 환경 | Host Domain | | ------- | ---------------------------------------------------------------- | | 검증(개발) | | | 상용 | | {% hint style="info" %} 본 문서에서 사용하는 도메인은 모든 국가에서 공용으로 사용할 수 있는 도메인입니다. 대한민국에서만 서비스 중인 기존 앱/게임의 도메인은 과거 도메인을 그대로 사용하시면 됩니다. (apis.onestore.co.kr) {% endhint %} ### 마켓 구분 코드 * Request header에 마켓 구분 코드 (x-market-code)가 추가 되었습니다. * 원스토어 글로벌 플랫폼에 서비스 되는 경우 마켓 구분 코드를 헤더에 추가하여 요청해야 합니다. * 마켓 구분 코드가 없는 경우에는 원스토어(기본 값)로 호출됩니다. | 마켓 구분 코드 | 서비스 대상 | | -------- | ----------- | | MKT\_ONE | 원스토어 (기본 값) | | MKT\_GLB | 원스토어 글로벌 | {% hint style="danger" %} 마켓 구분 코드에 따라 서버 API 응답으로 제공되는 시간의 기준이 다릅니다. MKT\_ONE : UTC+09 MKT\_GLB : UTC+00 {% endhint %} ## **원스토어 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 스킴을 사용하며 호출 샘플은 아래와 같습니다. ``` GET /v7/apps/com.onestore.game.goindol/purchases/inapp/products/product01/SANDBOXT000120004476 HTTP/1.1 Host: sbpp.onestore.net Authorization: Bearer 680b3621-1234-1234-1234-8adfaef561b4 ``` Authorization 헤더에는 위 예제와 같이 Bearer + 공백 + AccessToken이 대소문자 구분하여 정확히 입력되어야 합니다.\ Bearer의 값은 getAccessToken()을 호출하여 발급받은 AccessToken 값입니다. 잘못된 예 ``` Authorization: 680b3621-1234-1234-1234-8adfaef561b4 Authorization: bearer 680b3621-1234-1234-1234-8adfaef561b4 Authorization: Bearer <680b3621-1234-1234-1234-8adfaef561b4> Authorization:Bearer680b3621-1234-1234-1234-8adfaef561b4 ```
### **OAuth API 상세** **client\_id 및 client\_secret 확인** Client\_id와 Client\_secret 값은 "라이선스 관리" 메뉴에서 확인할 수 있습니다. ### **AccessToken 발급** * **URI :** /v7/oauth/token * **Method:** POST * **Request Parameter:** Form 형식 | Parameter Name | Description | Example | | -------------- | ---------------------------------- | -------------------------------------------- | | client\_id | 개발자센터에서 앱 등록 시 발급된 Client id 값 | 0000042301 | | client\_secret | 개발자센터에서 앱 등록 시 발급된 client secret 값 | vxIMAGcVz3DAx20uDBr/IDWNJAPNHFl7YruF4uxB6BI= | | grant\_type | 고정값 | client\_credentials | * **Request Header** : | Parameter Name | Description | Example | | -------------- | ----------------------------------------------------------------------- | ----------------------------------------------- | | Content-Type | Http 요청시 Content Type으로 반드시 application/x-www-form-urlencoded 로 설정되어야 함 | Content-Type: application/x-www-form-urlencoded | | x-market-code | 마켓 구분 코드 | x-market-code: MKT\_GLB | * **Example** ``` POST /v7/oauth/token HTTP/1.1 Host: apis.onestore.com Content-Type: application/x-www-form-urlencoded;charset=UTF-8 x-market-code: MKT_GLB grant_type=client_credentials&client_id=com.onestore.game.goindol&client_secret=vxIMAGcVz3DAx20uDBr/IDWNJAPNHFl7YruF4uxB6BI= ``` * **Response Body** : JSON 형식 | Element Name | Data Type | Data Size | Description | | ------------- | --------- | --------- | -------------------------- | | client\_id | String | 255 | OAuth 인증 client\_id | | access\_token | String | 36 | AccessToken | | token\_type | String | 6 | bearer 방식만 제공 | | expires\_in | Integer | 10 | token 만료기한, 단위 : 초(second) | | scope | String | 1024 | token 사용 범위 | * **Example :** ```json { "client_id":"0000000001", "access_token":"680b3621-1234-1234-1234-8adfaef561b4", "token_type":"bearer", "expires_in":3010, "scope":"DEFAULT" } ``` * **발급 예시** : 
curl -v -X POST https://sbpp.onestore.net/v7/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "x-market-code: MKT_GLB" \
  -d "grant_type=client_credentials" \
  -d "client_id=0000000001" \
  -d "client_secret=vxIMAGcVz3DAx20uDBr/IDWNJAPNHFl7YruF4uxB6BI="
  > POST /v7/oauth/token HTTP/1.1
  > Host: sbpp.onestore.net
  > User-Agent: curl/7.43.0
  > Accept: */*
  > Content-Type: application/x-www-form-urlencoded;charset=UTF-8
  > Content-Length: 35
  >
  * upload completely sent off: 35 out of 35 bytes
  < HTTP/1.1 200 200
  < Date: Wed, 02 May 2018 02:52:42 GMT
  < Server: Apache
  < Connection: close
  < Transfer-Encoding: chunked
  < Content-Type: application/json;charset=UTF-8
  <
  * Closing connection 0
  {"client_id":"0000000001","access_token":"680b3621-1234-1234-1234-8adfaef561b4","token_type":"bearer","expires_in":3600,"scope":"DEFAULT"}
검증(개발) 환경과 상용환경의 AccessToken은 독립적으로 관리되므로, 환경 별로 AccessToken을 분리하여 관리하셔야 합니다. ## **서버 API 상세** {% hint style="info" %} 2025년 3월 20일 개발자센터 개편의 영향으로 서버 API 요청 시 이용되던 packageName은 clientId로 변경되었습니다. * 3월 20일 이전 등록된 앱의 경우 클라이언트 ID 와 패키지명이 동일하므로, 변경에 대한 영향도가 없습니다. * 3월 20일 이후 등록된 앱의 경우 클라이언트 ID 가 PID와 동일하므로 참고 부탁 드립니다. {% endhint %} ### getPurchaseDetails (구매상품 상세조회) * **Desc :** 구매한 원스토어 관리형 상품의 상세정보를 조회합니다. 구매완료 시 전달받은 원스토어 purchaseToken(구매 토큰)을 이용하여 조회하여야 합니다. 월정액 상품의 purchaseToken으로 조회 시, 조회 실패(NoSuchData) 응답이 전달됩니다. * **URI :** /v7/apps/{clientId}/purchases/inapp/products/{productId}/{purchaseToken} * **Method :** GET * **Request Parameter :** Path Variable 형식 * String clientId : API를 호출하는 앱의 클라이언트 ID (Data Size : 128) * String productId : 상품 ID (Data Size : 150) * String purchaseToken : 구매 토큰 (Data Size : 20) * **Request Header:** | Parameter Name | Data Type | Required | Description | | -------------- | --------- | -------- | --------------------------------------- | | Authorization | String | true | Access Token API를 통해 발급받은 access\_token | | Content-Type | String | true | application/json | | x-market-code | String | false | 마켓 구분 코드 | * **Example** ```java Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4"); Request.setHeader("Content-Type", "application/json"); Request.setHeader("x-market-code", "MKT_GLB"); ``` * **Request Body :** 없음 * **Response Body** : JSON 형식 | Element Name | Data Type | Data Size | Description | | ---------------- | --------- | --------- | ---------------------------------------------- | | consumptionState | Integer | 1 | 구매한 상품의 소비상태 (0: 미소비, 1: 소비) | | developerPayload | String | 200 | 개발사가 제공한 결제 고유 식별자 | | purchaseState | Integer | 1 | 구매상태 ( 0: 구매완료, 1: 취소완료) | | purchaseTime | Long | 13 | 구매시간 (ms) | | purchaseId | String | 20 | 구매 ID | | acknowledgeState | Integer | 1 | 구매확인 상태( 0: Not Acknowledged, 1: Acknowledged) | | quantity | Integer | 2 | 구매 수량 | * **Example:** ``` HTTP/1.1 200 OK Content-type: application/json;charset=UTF-8 { "consumptionState": 0, "developerPayload": "developerPayload", "purchaseState": 0, "purchaseTime": 1345678900000, "purchaseId": "17070421461015116878", "acknowledgeState": 0, "quantity": 2 } ``` ### getRecurringPurchaseDetails (월정액 상품 구매 상세조회) * **Desc :** 구매한 원스토어 월정액 상품의 자동결제 상태와 마지막 구매상태의 상세정보를 조회합니다. 구매완료 시 전달받은 원스토어 purchaseToken(구매 토큰)을 이용하여 조회하여야 합니다. 관리형 상품의 purchaseToken으로 조회 시, 조회 실패(NoSuchData) 응답이 전달됩니다. * **URI :** /v7/apps/{clientId}/purchases/auto/products/{productId}/{purchaseToken} * **Method :** GET * **Request Parameter :** Path Variable 형식 * String clientId : API를 호출하는 앱의 클라이언트 ID (Data Size : 128) * String productId : 상품 ID (Data Size : 150) * String purchaseToken : 구매 토큰 (Data Size : 20) * **Request Header:** | Parameter Name | Data Type | Required | Description | | -------------- | --------- | -------- | --------------------------------------- | | Authorization | String | true | Access Token API를 통해 발급받은 access\_token | | Content-Type | String | true | application/json | | x-market-code | String | false | 마켓 구분 코드 | * **Example** ```java Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4"); Request.setHeader("Content-Type", "application/json"); Request.setHeader("x-market-code", "MKT_GLB"); ``` * **Request Body :** 없음 * **Response Body** : JSON 형식 | Element Name | Data Type | Data Size | Description | | ----------------- | --------- | --------- | ------------------------------------------------------ | | startTime | Long | 13 | 구매한 상품의 이용시작시간(ms) | | expiryTime | Long | 13 | 구매한 상품의 이용종료시간(ms) | | nextPaymentTime | Long | 13 | 다음 자동결제시간 | | autoRenewing | boolean | - | 이용종료시간(expiryTime)가 지난 후 자동결제 여부 | | cancelReason | Integer | 1 | 해지사유 (0 : 고객요청에 의한 해지, 1 : 기타 시스템 처리로 인한 해지 ) | | cancelledTime | Long | 13 | 해지시간(ms) | | acknowledgeState | Integer | 1 | 월정액 상품의 구매확인 상태( 0: Not Acknowledged, 1: Acknowledged) | | lastPurchaseId | String | 20 | 마지막에 자동결제된 구매ID | | lastPurchaseState | Integer | 1 | 마지막에 자동결제된 구매상태 (0 : 구매완료, 1 : 취소완료) | * **Example :** ```json HTTP/1.1 200 OK Content-type: application/json;charset=UTF-8 { "startTime": 1345678900000, "expiryTime": 1345678999999, "nextPaymentTime": 1345688000000, "autoRenewing": true, "cancelReason": 1, "cancelledTime": 1345679000000, "acknowledgeState": 0, "lastPurchaseId":"15081718460701027851", "lastPurchaseState": 0 } ``` 고객이 월정액 상품에 대하여 컨텐츠 사용 권한이 있는지 아래의 조건으로 판단이 가능합니다. * 현재시간이 expiryTime(구매한 상품의 이용종료시간)보다 작거나 같고, lastPurchaseState(마지막에 자동결제된 구매상태)가 0(구매완료) 상태인경우\ Ex) expiryTime >= 현재시간 AND lastPurchaseState == 0 ### acknowledgePurchase (구매상품 확인) * **Desc :** 구매한 관리형 또는 월정액 상품을 구매확인 상태로 변경한다. * **URI :** /v7/apps/{clientId}/purchases/all/products/{productId}/{purchaseToken}/acknowledge * **Method :** POST * **Request Parameter :** Path Variable 형식 * String clientId : API를 호출하는 앱의 클라이언트 ID (Data Size : 128) * String productId : 상품 ID (Data Size : 150) * String purchaseToken : 구매 토큰 (Data Size : 20) * **Request Header:** | Parameter Name | Data Type | Required | Description | | -------------- | --------- | -------- | --------------------------------------- | | Authorization | String | true | Access Token API를 통해 발급받은 access\_token | | Content-Type | String | true | application/json | | x-market-code | String | false | 마켓 구분 코드 | * **Example** ```java Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4"); Request.setHeader("Content-Type", "application/json"); Request.setHeader("x-market-code", "MKT_GLB"); ``` * **Request Body** : JSON 형식 | Element Name | Data Type | Required | Description | | ---------------- | --------- | -------- | ----------- | | developerPayload | String | false |


| * **Example :** ```json { "developerPayload": "your payload" } ``` * **Response Body :** JSON 형식 API 처리 성공 시 처리완료를 보다 직관적으로 판단할 수 있도록 아래 형식의 응답를 리턴합니다. 단, API 처리 실패 시에는 표준오류응답을 리턴합니다. | Element Name | Data Type | Data Size | Description | | ------------ | --------- | --------- | ----------- | | code | String | - | 응답 코드 | | message | String | - | 응답 메시지 | | result | Object | - |


| * **Example :** ```json HTTP/1.1 200 OK Content-type: application/json;charset=UTF-8 { "result" : { "code" : "Success", "message" : "Request has been completed successfully." } } ``` 원스토어는 3일 이내에 acknowledgePurchase API가 호출되지 않은 구매 건을 자동으로 취소합니다. 이에 따라 개발사는 반드시 해당 API를 호출해야 하며, SDK API 또는 서버 API를 통해 처리할 수 있습니다. 단, consumePurchase API가 호출된 구매 건은 acknowledge가 되었다고 판단하고 구매 취소를 하지 않습니다. ### consumePurchase (구매상품 소비) * **Desc :** 구매한 관리형 인앱 상품을 소비 상태로 변경한다. * **URI :** /v7/apps/{clientId}/purchases/inapp/products/{productId}/{purchaseToken}/consume * **Method :** POST * **Request Parameter :** Path Variable 형식 * String clientId : API를 호출하는 앱의 클라이언트 ID (Data Size : 128) * String productId : 상품 ID (Data Size : 150) * String purchaseToken : 구매 토큰 (Data Size : 20) * **Request Header:** | Parameter Name | Data Type | Required | Description | | -------------- | --------- | -------- | --------------------------------------- | | Authorization | String | true | Access Token API를 통해 발급받은 access\_token | | Content-Type | String | true | application/json | | x-market-code | String | false | 마켓 구분 코드 | * **Example** ```java Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4"); Request.setHeader("Content-Type", "application/json"); Request.setHeader("x-market-code", "MKT_GLB"); ``` * **Request Body** : JSON 형식 | Element Name | Data Type | Required | Description | | ---------------- | --------- | -------- | ----------- | | developerPayload | String | false |


| * **Example :** ```json { "developerPayload": "your payload" } ``` * **Response Body :** JSON 형식 API 처리 성공 시 처리완료를 보다 직관적으로 판단할 수 있도록 아래 형식의 응답를 리턴합니다. 단, API 처리 실패 시에는 표준오류응답을 리턴합니다. | Element Name | Data Type | Data Size | Description | | ------------ | --------- | --------- | ----------- | | code | String | - | 응답 코드 | | message | String | - | 응답 메시지 | | result | Object | - |


| * **Example :** ```json HTTP/1.1 200 OK Content-type: application/json;charset=UTF-8 { "result" : { "code" : "Success", "message" : "Request has been completed successfully." } } ``` ### cancelRecurringPurchase (자동결제 해지요청) * **Desc :** 월정액 상품의 자동결제 해지를 요청한다. 구독형 상품의 purchaseToken이용 시, 조회 실패(NoSuchData) 응답이 전달됩니다. * **URI :** /v7/apps/{clientId}/purchases/auto/products/{productId}/{purchaseToken}/cancel * **Method :** POST * **Request Parameter :** Path Variable 형식 * String clientId : API를 호출하는 앱의 클라이언트 ID (Data Size : 128) * String productId : 상품 ID (Data Size : 150) * String purchaseToken : 구매 토큰 (Data Size : 20) * **Request Header:** | Parameter Name | Data Type | Required | Description | | -------------- | --------- | -------- | --------------------------------------- | | Authorization | String | true | Access Token API를 통해 발급받은 access\_token | | Content-Type | String | true | application/json | | x-market-code | String | false | 마켓 구분 코드 | * **Example** ```java Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4"); Request.setHeader("Content-Type", "application/json"); Request.setHeader("x-market-code", "MKT_GLB"); ``` * **Request Body :** 없음 * **Response Body :** JSON 형식 API 처리 성공 시 처리완료를 보다 직관적으로 판단할 수 있도록 아래 형식의 응답를 리턴합니다. 단, API 처리 실패 시에는 표준오류응답을 리턴합니다. | Element Name | Data Type | Data Size | Description | | ------------ | --------- | --------- | ----------- | | code | String | - | 응답 코드 | | message | String | - | 응답 메시지 | | result | Object | - |


| * **Example :** ```json HTTP/1.1 200 OK Content-type: application/json;charset=UTF-8 { "result" : { "code" : "Success", "message" : "Request has been completed successfully." } } ``` ### reactiveRecurringPurchase (자동결제 해지 취소요청) * **Desc :** 월정액 상품의 자동결제 해지요청을 취소한다. 구독형 상품의 purchaseToken이용 시, 조회 실패(NoSuchData) 응답이 전달됩니다. * **URI :** /v7/apps/{clientId}/purchases/auto/products/{productId}/{purchaseToken}/reactivate * **Method :** POST * **Request Parameter :** Path Variable 형식 * String clientId : API를 호출하는 앱의 클라이언트 ID (Data Size : 128) * String productId : 상품 ID (Data Size : 150) * String purchaseToken : 구매 토큰 (Data Size : 20) * **Request Header:** | Parameter Name | Data Type | Required | Description | | -------------- | --------- | -------- | --------------------------------------- | | Authorization | String | true | Access Token API를 통해 발급받은 access\_token | | Content-Type | String | true | application/json | | x-market-code | String | false | 마켓 구분 코드 | * **Example** ```java Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4"); Request.setHeader("Content-Type", "application/json"); Request.setHeader("x-market-code", "MKT_GLB"); ``` * **Request Body :** 없음 * **Response Body :** JSON 형식 API 처리 성공 시 처리완료를 보다 직관적으로 판단할 수 있도록 아래 형식의 응답를 리턴합니다. 단, API 처리 실패 시에는 표준오류응답을 리턴합니다. | Element Name | Data Type | Data Size | Description | | ------------ | --------- | --------- | ----------- | | code | String | - | 응답 코드 | | message | String | - | 응답 메시지 | | result | Object | - |


| * **Example :** ```json HTTP/1.1 200 OK Content-type: application/json;charset=UTF-8 { "result" : { "code" : "Success", "message" : "Request has been completed successfully." } } ``` ### getVoidedPurchases (구매취소내역 조회) * **Desc :** 구매취소내역을 조회한다. * **URI :** /v7/apps/{clientId}/voided-purchases * **Method :** GET * **Request Parameter :** Path Variable 형식 * String clientId : API를 호출하는 앱의 클라이언트 ID (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:** | Parameter Name | Data Type | Required | Description | | -------------- | --------- | -------- | --------------------------------------- | | Authorization | String | true | Access Token API를 통해 발급받은 access\_token | | Content-Type | String | true | application/json | | x-market-code | String | false | 마켓 구분 코드 | * **Example** ```java Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4"); Request.setHeader("Content-Type", "application/json"); Request.setHeader("x-market-code", "MKT_GLB"); ``` * **Request Body :** 없음 * **Response Body :** | Element Name | Data Type | Data Size | Description | | ------------------ | ----------- | --------- | ----------------------------------------------------------------------------------- | | continuationKey | String | 41 | 구매취소 건이 최대조회건수보다 많을 경우 반환. 이후 요청시 전달받은 continuationKey 를 셋팅하여 호출하면 이후 내역을 조회 할 수 있음 | | voidedPurchaseList |


| - |


| | purchaseId | String | 20 | 구매 ID | | purchaseTime | Long | 13 | 구매시간(ms) | | voidedTime | Long | 13 | 구매취소시간(ms) | | purchaseToken | String | 20 | 구매 토큰 | | marketCode | String | - | 마켓 구분 코드 | * **Example :** ```json HTTP/1.1 200 OK Content-type: application/json;charset=UTF-8 { "continuationKey": "continuationKey", "voidedPurchaseList ": [ { "purchaseId": "19062709124410111299", "purchaseTime": 1345678900000, "voidedTime": 1345688900000, "purchaseToken": "19062709124410111299", "marketCode": "MKT_ONE" }, { "purchaseId": "19062709124410111300", "purchaseTime": 1345679900000, "voidedTime": 1345878900000, "purchaseToken": "19062709124410111299", "marketCode": "MKT_ONE" } ] } ``` ### getUnconfirmedPurchases (구매확인 미처리 내역 조회) * **Desc :** 구매확인(consume 또는 acknowledge) 처리되지 않은 구매목록을 반환합니다. * **URI :** /v7/apps/{clientId}/unconfirmed-purchases * **Method :** GET * **Request Parameter :** Path Variable 형식 * String clientId : API를 호출하는 앱의 클라이언트 ID (Data Size : 128) * **Request Parameter (Optional) :** Query String 형식 | Parameter Name | Data Type | Required | Description | | --------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | continuationKey | String | false |

구매 목록이 최대 조회 건수보다 많을 경우 반환

| | startTime | Long | false |

조회하고자 하는 구매 목록 검색 시작일(milliseconds)

| | endTime | Long | false |

조회하고자 하는 구매 목록 검색 종료일(milliseconds)

| | maxResults | Integer | false |

최대조회건수 (default : 100)

| * **Request Header:** | Parameter Name | Data Type | Required | Description | | -------------- | --------- | -------- | --------------------------------------- | | Authorization | String | true | Access Token API를 통해 발급받은 access\_token | | Content-Type | String | true | application/json | | x-market-code | String | false | 마켓 구분 코드 | * **Example** ```java Request.setHeader("Authorization", "Bearer 680b3512-1253-5642-1263-8adjbf651nb"); Request.setHeader("Content-Type", "application/json"); ``` * **Request Body : N/A** * **Response Body**:
| **Element Name** | **Data Type** | **Data Size** | **Description** | | -------------------------------------------------- | ----------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | continuationKey | String |


|

구매 목록이 최대 조회 건수보다 많을 경우 반환

| | unconfirmedPurchaseList \[ |


|


|


| | { |


|


|


| | type | String | - | 상품 타입 | | orderId | String | 40 | 결제 ID | | productId |

String

| 150 | 개발자센터에 상품 등록 시 지정한 인앱상품 ID | | purchaseToken | String | 20 | 구매 토큰 | | purchaseId | String | 20 | 구매 ID | | purchaseTime | Long | 13 | 구매시간 (ms) | | purchaseState | Integer | 1 | 구매상태 (0: 구매완료, 1: 취소완료) | | developerPayload | String | 200 | 구매건을 식별하기 위해 개발사에서 관리하는 식별자 | | quantity | Integer |


| 구매한 상품의 수량 | | marketCode | String | - |

마켓 구분 코드

| | } |


|


|


| | ] |


|


|


| * **Example** ```java HTTP/1.1 200 OK Content-type: application/json;charset=UTF-8 { "continuationKey": "continuationKey", "unconfirmedPurchaseList ": [ { "type": "inapp", "orderId": "01239349082349823489342", "productId": "다이아100_20170818000000", "purchaseToken": "19062709124410111299", "purchaseId": "19062709124410111299", "purchaseTime": 1345678900000, "purchaseState": 0, "developerPayload": "E23DEFB029F84F4383ECB0E53B46B6A2", "quantity": 1, "marketCode": "MKT_ONE" }, { "type": "inapp", "orderId": "01239349082349823489343", "productId": "루비300_20170818000000", "purchaseToken": "19062709124410111299", "purchaseId": "19062709124410111300", "purchaseTime": 1345679900000, "purchaseState": 0, "developerPayload": "T_RPAY_27_201707120110880", "quantity": 2, "marketCode": "MKT_ONE" } ] } ``` ### getSubscriptionDetail (구독 상세 조회) * **Desc :** 구독 상세 내역을 조회한다. * **URI :** /v7/apps/{clientId}/purchases/subscription/products/{productId}/{purchaseToken} * **Method :** GET * **Request Parameter :** Path Variable 형식 * String clientId : API를 호출하는 앱의 클라이언트 ID (Data Size : 128) * String productId : 상품 ID (Data Size : 150) * String purchaseToken : 구매 토큰 (Data Size : 20) * **Request Header:** | Parameter Name | Data Type | Required | Description | | -------------- | --------- | -------- | --------------------------------------- | | Authorization | String | true | Access Token API를 통해 발급받은 access\_token | | Content-Type | String | true | application/json | | x-market-code | String | false | 마켓 구분 코드 | * **Example** 
Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4");
  Request.setHeader("Content-Type", "application/json");
  Request.setHeader("x-market-code", "MKT_GLB");
* **Request Body :** 없음 * **Response Body :**
Element NameData TypeData SizeDescription
acknowledgementStateInteger1구매확인 상태( 0: Not Acknowledged, 1: Acknowledged)
developerPayloadString200개발사가 제공한 결제 고유 식별자
autoRenewingboolean-

다음결제 갱신여부

  • 구독해지예약,해지,만료 : false
  • 나머지 : true
paymentStateInteger1

구독결제 수신여부

  • null: 만료 상태
  • 0: 결제가 완료 되지 않은 상태
  • 1: 결제요청 후 결제완료가 된 상태
  • 2: 무료기간으로 처리된 상태
  • 3: 상품 업/다운그레이드 시 DEFERRED옵션으로 처리된 상태
priceAmountString-구매금액
priceAmountMicrosLong-구매금액 * 100만
nextPriceAmountString-다음구매금액
nextPriceAmountMicrosLong-다음구매금액 * 100만
nextPaymentTimeMillisLong13다음구매시간(ms)
priceCurrencyCodeString-통화코드
countryCodeString-국가코드(KR 고정)
startTimeMillisLong13구독 시작(첫 결제)시간(ms)
expiryTimeMillisLong13구독 만료시간(ms)
pauseStartTimeMillisLong13일시정지 시작일시(ms)-일시정지예약/일시정지 시에만 존재
pauseEndTimeMillisLong13일시정지 시작일시(ms)-일시정지예약/일시정지 시에만 존재
autoResumeTimeMillisLong13

일시정지 후 재구독 시간

  • 정상 구독 중: null
  • 일시정지 예약/확정/일시정지중: 다음결제일 + 일시정지일자
linkedPurchaseTokenString20구독상품 변경 시 이전 purchaseToken, 변경한 적이 없으면 null
lastPurchaseIdString20마지막 구매ID
cancelledTimeMillis
Long13구독 해지시간(ms)
cancelReasonInteger1

구독 해지사유

  • 0 : 고객요청
  • 1 : 기타
promotionPriceObject-프로모션 금액 정보
promotionPrice.promotionPriceString-프로모션 금액
promotionPrice.promotionPriceMicrosLong-프로모션 금액 정보 * 100만
promotionPrice.promotionPeriodInt-프로모션 적용 회차
priceChangeObject-가격변동정보
priceChange.seqInteger-가격변동 시퀀스
priceChange.previousPriceString-이전 가격
priceChange.previousPriceMicrosLong-이전 가격 * 100만
priceChange.newPriceString-신규 가격
priceChange.newPriceMicrosLong-신규 가격 * 100만
priceChange.applyTimeMillisLong13적용일자(ms)
priceChange.agreementBoolean-가격 변동 동의 여부
priceChange.agreementDueDateTimeMillisLong13

가격 변동 동의 만료 시간(ms)

(정책 부연 설명)

Value = 가격변경일 +7+30일
사용자는 동의만료일 이후 첫 자동결제 시점까지 동의가능함.

* **Example :** ```json HTTP/1.1 200 OK Content-type: application/json;charset=UTF-8 { "acknowledgementState":1, "autoRenewing":true, "paymentState":1, "lastPurchaseId": "20202394820938409234" "linkedPurchaseToken":null, "priceAmount":"100", "priceAmountMicros":100000000, "nextPriceAmount":"150", "nextPriceAmountMicros":150000000, "nextPaymentTimeMillis": 1623337199000, "priceCurrencyCode":"KRW", "countryCode":"KR", "startTimeMillis":1623337199000, "expiryTimeMillis":1625929199000, "pauseStartTimeMillis":1625929199000, "pauseEndTimeMillis":1625929199000, "autoResumeTimeMillis":1625878800000, "cancelledTimeMillis":1625929199000, "cancelReason":0, "promotionPrice":{ "promotionPrice":"100", "promotionPriceMicros":100000000, "promotionPeriod":30 }, "priceChange":{ "seq": 1, "previousPrice":"100", "previousPriceMicros":100000000, "newPrice":"500", "newPriceMicros":500000000, "applyTimeMillis":1625670000000, "agreement":false, "agreementDueDateTimeMillis": 1345678920000 } } ``` ### cancelSubscription (구독결제 해지요청) * **Desc :** 구독형 상품의 자동결제 해지를 요청한다. 단, 요청 시점에 구독상태가 일시중지, 결제유예, 계정보류일 경우 즉시 해지를 요청한다. * **URI :** /v7/apps/{clientId}/purchases/subscription/products/{productId}/{purchaseToken}/cancel * **Method :** POST * **Request Parameter :** Path Variable 형식 * String clientId : API를 호출하는 앱의 클라이언트 ID (Data Size : 128) * String productId : 상품 ID (Data Size : 150) * String purchaseToken : 구매 토큰 (Data Size : 20) * **Request Header:** | Parameter Name | Data Type | Required | Description | | -------------- | --------- | -------- | --------------------------------------- | | Authorization | String | true | Access Token API를 통해 발급받은 access\_token | | Content-Type | String | true | application/json | | x-market-code | String | false | 마켓 구분 코드 | * **Example** ```java Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4"); Request.setHeader("Content-Type", "application/json"); Request.setHeader("x-market-code", "MKT_GLB"); ``` * **Request Body :** 없음 * **Response Body :** JSON 형식 API 처리 성공 시 처리완료를 보다 직관적으로 판단할 수 있도록 아래 형식의 응답를 리턴합니다. 단, API 처리 실패 시에는 표준오류응답을 리턴합니다. | Element Name | Data Type | Data Size | Description | | ------------ | --------- | --------- | ----------- | | code | String | - | 응답 코드 | | message | String | - | 응답 메시지 | | result | Object | - |


| * **Example :** ```json HTTP/1.1 200 OK Content-type: application/json;charset=UTF-8 { "result" : { "code" : "Success", "message" : "Request has been completed successfully." } } ``` ### reactivateSubscription (구독결제 해지 취소요청) * **Desc :** 구독형 상품의 자동결제 해지요청을 취소한다. 단, 즉시해지된 경우 해지요청을 취소할 수 없다. * **URI :** /v7/apps/{clientId}/purchases/subscription/products/{productId}/{purchaseToken}/reactivate * **Method :** POST * **Request Parameter :** Path Variable 형식 * String clientId : API를 호출하는 앱의 클라이언트 ID (Data Size : 128) * String productId : 상품 ID (Data Size : 150) * String purchaseToken : 구매 토큰 (Data Size : 20) * **Request Header:** | Parameter Name | Data Type | Required | Description | | -------------- | --------- | -------- | --------------------------------------- | | Authorization | String | true | Access Token API를 통해 발급받은 access\_token | | Content-Type | String | true | application/json | | x-market-code | String | false | 마켓 구분 코드 | * **Example** ```java Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4"); Request.setHeader("Content-Type", "application/json"); Request.setHeader("x-market-code", "MKT_GLB"); ``` * **Request Body :** 없음 * **Response Body :** JSON 형식 API 처리 성공 시 처리완료를 보다 직관적으로 판단할 수 있도록 아래 형식의 응답를 리턴합니다. 단, API 처리 실패 시에는 표준오류응답을 리턴합니다. | Element Name | Data Type | Data Size | Description | | ------------ | --------- | --------- | ----------- | | code | String | - | 응답 코드 | | message | String | - | 응답 메시지 | | result | Object | - |


| * **Example :** ```json HTTP/1.1 200 OK Content-type: application/json;charset=UTF-8 { "result" : { "code" : "Success", "message" : "Request has been completed successfully." } } ``` ### deferSubscription (구독결제 연기요청) * **Desc :** 구독형 상품의 다음 결제일을 연기한다. * **URI :** /v7/apps/{clientId}/purchases/subscription/products/{productId}/{purchaseToken}/defer * **Method :** POST * **Request Parameter :** Path Variable 형식 * String clientId : API를 호출하는 앱의 클라이언트 ID (Data Size : 128) * String productId : 상품 ID (Data Size : 150) * String purchaseToken : 구매 토큰 (Data Size : 20) * **Request Header:** | Parameter Name | Data Type | Required | Description | | -------------- | --------- | -------- | --------------------------------------- | | Authorization | String | true | Access Token API를 통해 발급받은 access\_token | | Content-Type | String | true | application/json | | x-market-code | String | false | 마켓 구분 코드 | * **Example** ```java Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4"); Request.setHeader("Content-Type", "application/json"); Request.setHeader("x-market-code", "MKT_GLB"); ``` * **Request Body :** JSON 형식 | Parameter Name | Data Type | Required | Description | | -------------- | --------- | -------- | ------------------------------------------------------------------ | | deferPeriod | Integer | true |

연기 기간

| * **Example :** ```json Content-type: application/json;charset=UTF-8 { "deferPeriod" : 3 } ``` * **Response Body :** JSON 형식 API 처리 성공 시 처리완료를 보다 직관적으로 판단할 수 있도록 아래 형식의 응답를 리턴합니다. 단, API 처리 실패 시에는 표준오류응답을 리턴합니다. | Element Name | Data Type | Data Size | Description | | ------------ | --------- | --------- | ----------- | | code | String | - | 응답 코드 | | message | String | - | 응답 메시지 | | result | Object | - |


| * **Example :** ```json HTTP/1.1 200 OK Content-type: application/json;charset=UTF-8 { "result" : { "code" : "Success", "message" : "Request has been completed successfully." } } ``` ## 표준응답규격 ### 표준응답코드 | Code | Message | Description | HTTP Status Code | 대상 API | | -------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------- | | AccessBlocked | The request was blocked. | 요청이 차단되었습니다. | 403 - Fobidden | 공통 | | AccessTokenExpired | Access token has expired. | Access 토큰이 만료되었습니다. | 401 - Unauthorized | 공통 | | BadRequest | The request are invalid. | 잘못된 요청입니다. | 400 - Bad Request | 공통 | | DeveloperPayloadNotMatch | The request developerPayload does not match the value passed in the purchase request. | 구매요청 시 전달된 developerPayload값과 일치하지 않습니다. | 400 - Bad Request |

acknowledgePurchase
consumePurchase

| | InternalError | An undefined error has occurred. | 정의되지 않은 오류가 발생하였습니다. | 500 - Internal Server Error | 공통 | | InvalidAccessToken | Access token is invalid. | Access 토큰이 유효하지 않습니다. | 401 - Unauthorized | 공통 | | InvalidAuthorizationHeader | Authorization header is invalid. | Authorization 헤더의 값이 유효하지 않습니다. | 400 - Bad Request | 공통 | | InvalidConsumeState | The purchase consumption status cannot be changed or has already been changed. | 소비상태 변경이 불가하거나, 이미 변경완료 되었습니다. | 409 - Conflict | consumePurchase | | InvalidContentType | The request content-type is invalid. | 잘못된 Content Type 입니다. | 415 - Unsupported Media Type | 공통 | | InvalidPurchaseState | Purchase history does not exist or is not completed. | 구매내역이 존재하지 않거나, 구매완료 상태가 아닙니다. | 409 - Conflict |

acknowledgePurchase
consumePurchase

| | InvalidRequest | Request parameters are invalid. \[ field1, field2, ... ] | 입력값이 유효하지 않습니다. \[ field1, field2, ... ] | 400 - Bad Request | 공통 | | MethodNotAllowed | HTTP method not supported. | 지원하지 않는 HTTP Method 입니다. | 405 - Method Not Allowed | 공통 | | NoSuchData | The requested data could not be found. | 조회된 결과값이 존재하지 않습니다. | 404 - Not Found |

getPurchaseDetails
getRecurringPurchaseDetails

| | RequiredValueNotExist | Request parameters are required. \[ field1, field2, ... ] | 필수값이 존재하지 않습니다. \[ field1, field2, ... ] | 400 - Bad Request | 공통 | | ResourceNotFound | The requested resource could not be found. | 요청한 자원이 존재하지 않습니다. | 404 - Not Found | 공통 | | ServiceMaintenance | System maintenance is in progress. | 서비스 점검중입니다. | 503 - Service Temporarily Unavailable | 공통 | | Success | The request has been completed successfully. | 정상처리 되었습니다. | 200 - Success |

acknowledgePurchase
consumePurchase
cancelRecurringPurchase
reactivateRecurringPurchase

| | UnauthorizedAccess | Not authorized to this API. | 해당 API에 접근권한이 없습니다. | 403 - Fobidden | 공통 | ### 표준오류 응답규격 서버 API에서는 정상적인 응답 외에 오류발생 시, 아래의 Example과 같은 형식의 표준오류응답을 리턴합니다. 아래 내용을 참고하시기 바랍니다. * **Response Body :** JSON 형식 | Element Name | Data Type | Data Size | Description | | ------------ | --------- | --------- | ----------- | | code | String | - | 응답 코드 | | message | String | - | 응답 메시지 | | error | Object | - |


| * **Example** ```json HTTP/1.1 400 Bad Request Content-type: application/json;charset=UTF-8 { "error" : { "code" : "NoSuchData", "message" : "The requested data could not be found." } } ``` ## **공통 코드** ### **상품타입 코드** | Code | Name | Description | | ------------ | ------ | --------------- | | inapp | 관리형 상품 | 소비성/영구성/기간제 상품 | | auto | 월정액 상품 | 월 자동결제 상품 | | subscription | 구독형 상품 | 구독형(자동결제) 상품 | | all | 전체 상품 | 관리형 상품 + 월정액 상품 | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://onestore-dev.gitbook.io/dev/tools/billing/v21/serverapi.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.