# ONE store IAP Server API (API V7)

## Overview  <a href="#onestoreiapserverapi-apiv7-overview" id="onestoreiapserverapi-apiv7-overview"></a>

The ONE store IAP Server API indicates Open API to check the data of in-app, which has been billed on ONE store or to change the billing status.\
OAuth authentication is necessary to use this API.

### HOST Domain  <a href="#onestoreiapserverapi-apiv7-hosturl" id="onestoreiapserverapi-apiv7-hosturl"></a>

The Host Domain used in this document is as follows:

| ONE store Environment | Host Domain                                                    |
| --------------------- | -------------------------------------------------------------- |
| Sandbox (development) | [https://sbpp.onestore.net](https://sbpp.onestore.net/)        |
| Commercial            | [https://iap-apis.onestore.net](https://iap-apis.onestore.net) |

{% hint style="info" %}
The domains used in this document can be used for both domestic and global purpose.

For existing apps/games that are only available in South Korea, please continue using the previous domain. (apis.onestore.co.kr)
{% endhint %}

### Market Classification&#x20;

* The Market Classification Code (x-market-code) has been added to the request header.
* For ONE store Global Platform services, the header should include the acquired Market Classification Code when utilizing the server API.
* If the Market Classification Code is absent, it will be treated as an app for Korea.

\<Example>&#x20;

```
curl --location '{global domain}/v7/apps/com.sample/purchases/inapp/products/{productId}/{purchaseToken}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}' \
--header 'x-market-code: MKT_GLB'
 

```

| Market Code | Service Country  |
| ----------- | ---------------- |
| MKT\_ONE    | Korea            |
| MKT\_GLB    | Global           |

{% hint style="danger" %}
The criteria for the time provided by server API responses vary according to the market segmentation code.

MKT\_ONE : UTC+09

MKT\_GLB : UTC+00 &#x20;
{% endhint %}

## ONE store OAuth  <a href="#onestoreiapserverapi-apiv7-onestoreoauth" id="onestoreiapserverapi-apiv7-onestoreoauth"></a>

### OAuth Overview <a href="#onestoreiapserverapi-apiv7-oauthoverview" id="onestoreiapserverapi-apiv7-oauthoverview"></a>

OAuth authentication is necessary for interworking with ONE store Server Open API.

* Understanding ONE store OAuth v2
  * AccessToken is the value that can be issued through ONE store's Server Open API, and it is used as the authentication value when the Server Open API provided by ONE store is called.
  * AccessToken has a default duration of 3,600 seconds. When the valid duration expires or is less than 600 seconds, if you call getAccessToken(), a new AccessToken will be issued.&#x20;
    * The existing AccessToken is also available until the valid duration ends.
    * Numerous AccessTokens get issued in this way, and therefore you can acquire and use AccessTokens differentiated for each service instance of the developer.
*   The typical interworking flow is as follows\


    <figure><img src="https://2218522982-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgStyyzRzNh9x2u93ZH03%2Fuploads%2FbCZs261FKOt2APjeuVBC%2Fimage.png?alt=media&#x26;token=0a6413a6-a2f7-4814-9e7a-bd846a09487b" alt=""><figcaption></figcaption></figure>
* Call the process for obtaining AccessToken (no.1) when the authentication error occurs during API calls.

\
Use the Authorization Bearer scheme to call ONE store IAP Server API, and the call sample is as shown below.&#x20;



```
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
```

'Bearer + Vavant + AccessToken' must be entered exactly and case-sensitive in the Authorization header as seen in the example above.The Bearer's value is the value of AccessToken, which has been issued by calling upon getAccessToken().

\
Incorrect example

```
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 Details <a href="#onestoreiapserverapi-apiv7-oauthapidetails" id="onestoreiapserverapi-apiv7-oauthapidetails"></a>

**Check client\_id & client\_secret**

The values for `Client_id` and `Client_secret` can be found in the "License Management" menu.\


### **Issue AccessToken**

* **URI :** /v7/oauth/token
* **Method:** POST
*   **Request Parameter:** Form format

    | **Parameter Name** | **Description**                                                                                  | **Example**                                  |
    | ------------------ | ------------------------------------------------------------------------------------------------ | -------------------------------------------- |
    | client\_id         | Typically the same as packageName                                                                | 0000042301                                   |
    | client\_secret     | The client secret value that has been issued when the app is registered on the Developer Center. | vxIMAGcVz3DAx20uDBr/IDWNJAPNHFl7YruF4uxB6BI= |
    | grant\_type        | The fixed value                                                                                  | client\_credentials                          |
*   **Request Header** :&#x20;

    | **Parameter Name** | **Description**                                                                       | **Example**                                     |
    | ------------------ | ------------------------------------------------------------------------------------- | ----------------------------------------------- |
    | Content-Type       | At the request of http, Content-Type must be set as application/x-www-form-urlencoded | Content-Type: application/x-www-form-urlencoded |
    | x-market-code      | [Market classification code](#market-classification)                                  | x-market-code: MKT\_GLB                         |


*   **Example**

    <pre data-overflow="wrap"><code><strong>POST /v7/oauth/token HTTP/1.1
    </strong>Host: apis.onestore.com
    Content-Type: application/x-www-form-urlencoded;charset=UTF-8
    x-market-code: MKT_GLB

    grant_type=client_credentials&#x26;client_id=0000042301&#x26;client_secret=vxIMAGcVz3DAx20uDBr/IDWNJAPNHFl7YruF4uxB6BI=
    </code></pre>
*   **Response Body**: JSON format

    | **Element Name** | **Data Type** | **Data Size** | **Description**                          |
    | ---------------- | ------------- | ------------- | ---------------------------------------- |
    | client\_id       | String        | 255           | OAuth authentication client\_id          |
    | access\_token    | String        | 36            | AccessToken                              |
    | token\_type      | String        | 6             | Provides the bearer method only          |
    | expires\_in      | Integer       | 10            | Token expiration period, unit: second(s) |
    | scope            | String        | 1024          | Token use range                          |
*   **Example:**&#x20;

    ```json
    {    
        "client_id":"0000042301",
        "access_token":"680b3621-1234-1234-1234-8adfaef561b4",
        "token_type":"bearer",
        "expires_in":3010,
        "scope":"DEFAULT"
    }
    ```
*   **Example of issuance**: \


    {% code overflow="wrap" %}
    ```bash
    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=0000042301" \
    -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":"0000042301","access_token":"680b3621-1234-1234-1234-8adfaef561b4","token_type":"bearer","expires_in":3600,"scope":"DEFAULT"}
    ```
    {% endcode %}

    AccessToken in the review (development) and commercial environments is managed independently, and therefore you must manage AccessToken separately per environment.

## Server API Details <a href="#onestoreiapserverapi-apiv7-serverapidetails" id="onestoreiapserverapi-apiv7-serverapidetails"></a>

{% hint style="info" %}
Due to the Developer Center update on March 20, 2025, the `packageName` used for server API requests has been changed to `clientId`.

* For apps registered before March 20, the client ID and package name are identical, so there is no impact from this change.
* For apps registered after March 20, the client ID is the same as the PID. Please take note of this.
{% endhint %}

### getPurchaseDetails (Check purchased in-app product details) <a href="#onestoreiapserverapi-apiv7-getpurchasedetails-checkpurchasedin-appproductdetails" id="onestoreiapserverapi-apiv7-getpurchasedetails-checkpurchasedin-appproductdetails"></a>

* **Desc:** Checks the details of purchased ONE store Managed Products. You must search the details by using the ONE store purchaseToken (purchase token), which has been received at the completion of the purchase. If you search the details with purchaseToken of Monthly auto-renewal product, then the check failure (NoSuchData) response will be transmitted.
* **URI :** /v7/apps/{clientId}/purchases/inapp/products/{productId}/{purchaseToken}
* **Method :** GET
* **Request Parameter :** Path Variable format
  * String clientId : Client ID of the app that calls API (Data Size : 128)
  * String productId : Product ID (Data Size : 150)
  * String purchaseToken : Purchase token (Data Size : 20)
*   **Request Header:**&#x20;

    | Parameter Name | Data Type | Required | Description                                           |
    | -------------- | --------- | -------- | ----------------------------------------------------- |
    | Authorization  | String    | true     | The access\_token issued through the Access Token API |
    | Content-Type   | String    | true     | application/json                                      |
    | x-market-code  | String    | false    | Market classification code                            |
*   **Example**&#x20;

    ```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 :** N/A
*   **Response Body** : JSON format

    | **Element Name** | **Data Type** | **Data Size** | **Description**                                                         |
    | ---------------- | ------------- | ------------- | ----------------------------------------------------------------------- |
    | consumptionState | Integer       | 1             | The 'consume' status of purchased in-app (0: not consumed, 1: consumed) |
    | developerPayload | String        | 200           | Unique billing identifier provided by the developer                     |
    | purchaseState    | Integer       | 1             | Purchase status (0: purchase completed, 1: cancellation completed)      |
    | purchaseTime     | Long          | 13            | Purchase time (ms)                                                      |
    | purchaseId       | String        | 20            | Purchase ID                                                             |
    | acknowledgeState | Integer       | 1             | Purchase acknowledgement status (0: not acknowledged, 1: acknowledged)  |
    | quantity         | Integer       | 2             | The 'consume' status of purchased in-app (0: not consumed, 1: consumed) |
*   **Example:**&#x20;

    ```
    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 (Check purchased monthly auto-renewal product details)  <a href="#onestoreiapserverapi-apiv7-getrecurringpurchasedetails-checkpurchasedmonthlyauto-renewalproductdetai" id="onestoreiapserverapi-apiv7-getrecurringpurchasedetails-checkpurchasedmonthlyauto-renewalproductdetai"></a>

* **Desc:** Checks the automatic payment status of purchased ONE store Monthly auto-renewal products and the details of the last purchase status. You must check them by using the ONE store purchaseToken (purchase token), which has been received at the completion of the purchase. If you check the details with purchaseToken of Managed Product, then the check failure (NoSuchData) response will be transmitted.
* **URI :** /v7/apps/{clientId}/purchases/auto/products/{productId}/{purchaseToken}
* **Method :** GET
* **Request Parameter :** Path Variable format
  * String clientId : Client ID of the app that calls API (Data Size : 128)
  * String productId : Product ID (Data Size : 150)
  * String purchaseToken : Purchase token (Data Size : 20)
*   **Request Header:**&#x20;

    | Parameter Name | Data Type | Required | Description                                           |
    | -------------- | --------- | -------- | ----------------------------------------------------- |
    | Authorization  | String    | true     | The access\_token issued through the Access Token API |
    | Content-Type   | String    | true     | application/json                                      |
    | x-market-code  | String    | false    | Market classification code                            |
*   **Example**&#x20;

    ```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 :** N/A
*   **Response Body** : JSON format

    | **Element Name**  | **Data Type** | **Data Size** | **Description**                                                                                            |
    | ----------------- | ------------- | ------------- | ---------------------------------------------------------------------------------------------------------- |
    | startTime         | Long          | 13            | The use start time of purchased in-app (ms)                                                                |
    | expiryTime        | Long          | 13            | The use end time of purchased in-app (ms)                                                                  |
    | nextPaymentTime   | Long          | 13            | The next automatic payment time                                                                            |
    | autoRenewing      | boolean       | -             | Whether or not the automatic payment was made after the end time has been exceeded.                        |
    | cancelReason      | Integer       | 1             | Reasons for cancellation (0: cancellation by the user request, 1: cancellation by other system processing) |
    | cancelledTime     | Long          | 13            | cancellation time (ms)                                                                                     |
    | acknowledgeState  | Integer       | 1             | The purchase acknowledgement status of Monthly auto-renewal product (0: not acknowledged, 1: acknowledged) |
    | lastPurchaseId    | String        | 20            | The Purchase ID of the last automatic payment                                                              |
    | lastPurchaseState | Integer       | 1             | The purchase status of the last automatic payment (0: purchase completed, 1: cancellation completed)       |
*   **Example :**&#x20;

    ```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
    }
    ```

    With the following conditions, you can determine whether the user has the right to use the content of the Monthly auto-renewal product.

    * If the current time is smaller than or equal to expiryTime(the use end time of purchased in-app) and lastPurchaseState(the purchase status of the last automatic payment) is 0 (the purchase completed)Ex) expiryTime >= current time AND lastPurchaseState == 0

### acknowledgePurchase (Confirm purchased in-app products)  <a href="#onestoreiapserverapi-apiv7-acknowledgepurchase-confirmpurchasedin-appproducts" id="onestoreiapserverapi-apiv7-acknowledgepurchase-confirmpurchasedin-appproducts"></a>

* **Desc :** Changes the status of purchased managed product or monthly auto-renewal product into the 'acknowledged' status.
* **URI :** https://{host}/v7/apps/{clientId}/purchases/all/products/{productId}/{purchaseToken}/acknowledge
* **Method :** POST
* **Request Parameter :** Path Variable format
  * String clientId : Client ID of the app that calls API (Data Size : 128)
  * String productId : Product ID (Data Size : 150)
  * String purchaseToken : Purchase token (Data Size : 20)
*   **Request Header:**&#x20;

    | Parameter Name | Data Type | Required | Description                                           |
    | -------------- | --------- | -------- | ----------------------------------------------------- |
    | Authorization  | String    | true     | The access\_token issued through the Access Token API |
    | Content-Type   | String    | true     | application/json                                      |
    | x-market-code  | String    | false    | Market classification code                            |
*   **Example**&#x20;

    ```java
    Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4");
    Request.setHeader("Content-Type", "application/json");
    Request.setHeader("x-market-code", "MKT_GLB");
    ```
*   **Response Body** : JSON forat

    | **Element Name** | **Data Type** | **Required** | **Description** |
    | ---------------- | ------------- | ------------ | --------------- |
    | developerPayload | String        | false        | <p><br></p>     |
*   **Example :**&#x20;

    <pre class="language-json"><code class="lang-json"><strong>{
    </strong>    "developerPayload": "your payload"
    }
    </code></pre>
* **Response Body :** JSON format\
  The response is returned in the following format to allow for a more intuitive determination of the process completion when API processing is successful. However, when the API processing fails, it returns the standard error response.

| **Element Name** | **Data Type** | **Data Size** | **Description**  |
| ---------------- | ------------- | ------------- | ---------------- |
| code             | String        | -             | Response code    |
| message          | String        | -             | Response message |
| result           | Object        | -             | <p><br></p>      |

*   **Example :**&#x20;

    ```
    HTTP/1.1 200 OK
    Content-type: application/json;charset=UTF-8
    {
        "result" : {
            "code" : "Success",
            "message" : "Request has been completed successfully."
        }
    }
    ```





ONE store shall automatically cancel the purchase, which has not been called by acknowledgePurchase API within 3 days.

Therefore, the developer MUST call this API and then he/she can process through SDK API or server API.

However, the purchase called by consumePurchase API will be considered 'acknowledged' and it will not be canceled.

### consumePurchase (Consume purchased in-app products) <a href="#onestoreiapserverapi-apiv7-consumepurchase-consumepurchasedin-appproducts" id="onestoreiapserverapi-apiv7-consumepurchase-consumepurchasedin-appproducts"></a>

* **Desc :** Changes the status of purchased Managed product into the 'consumed' status.
* **URI :** /v7/apps/{clientId}/purchases/inapp/products/{productId}/{purchaseToken}/consume
* **Method :** POST
* **Request Parameter :** Path Variable format
  * String clientId : Client ID of the app that calls API (Data Size : 128)
  * String productId : Product ID (Data Size : 150)
  * String purchaseToken : Purchase token (Data Size : 20)
*   **Request Header:**&#x20;

    | Parameter Name | Data Type | Required | Description                                           |
    | -------------- | --------- | -------- | ----------------------------------------------------- |
    | Authorization  | String    | true     | The access\_token issued through the Access Token API |
    | Content-Type   | String    | true     | application/json                                      |
    | x-market-code  | String    | false    | Market classification code                            |
*   **Example**&#x20;

    ```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 format

    | **Element Name** | **Data Type** | **Required** | **Description** |
    | ---------------- | ------------- | ------------ | --------------- |
    | developerPayload | String        | false        | <p><br></p>     |
*   **Example :**

    ```json
    {
        "developerPayload": "your payload"
    }
    ```
* **Response Body :** JSON 형식\
  The response is returned in the following format to allow for a more intuitive determination of the process completion when API processing is successful. However, when the API processing fails, it returns the standard error response.

| **Element Name** | **Data Type** | **Data Size** | **Description**  |
| ---------------- | ------------- | ------------- | ---------------- |
| code             | String        | -             | Response code    |
| message          | String        | -             | Response message |
| result           | Object        | -             | <p><br></p>      |

*   **Example :**&#x20;

    ```json
    HTTP/1.1 200 OK
    Content-type: application/json;charset=UTF-8
    {
        "result" : {
            "code" : "Success",
            "message" : "Request has been completed successfully."
        }
    }
    ```

### cancelRecurringPurchase (Request to cancel automatic payment) <a href="#onestoreiapserverapi-apiv7-cancelrecurringpurchase-requesttocancelautomaticpayment" id="onestoreiapserverapi-apiv7-cancelrecurringpurchase-requesttocancelautomaticpayment"></a>

* **Desc :** Requests the cancellation of automatic payment of monthly auto-renewal products. If using the purchaseToken of a subscription product, a 'NoSuchData' response is sent.
* **URI :** /v7/apps/{clientId}/purchases/auto/products/{productId}/{purchaseToken}/cancel
* **Method :** POST
* **Request Parameter :** Path Variable format
  * String clientId : Client ID of the app that calls API (Data Size : 128)
  * String productId : Product ID (Data Size : 150)
  * String purchaseToken : Purchase token (Data Size : 20)
*   **Request Header:**&#x20;

    | Parameter Name | Data Type | Required | Description                                           |
    | -------------- | --------- | -------- | ----------------------------------------------------- |
    | Authorization  | String    | true     | The access\_token issued through the Access Token API |
    | Content-Type   | String    | true     | application/json                                      |
    | x-market-code  | String    | false    | Market classification code                            |
*   **Example**&#x20;

    ```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 :** N/A
* **Response Body :** JSON format\
  The response is returned in the following format to allow for a more intuitive determination of the process completion when API processing is successful. However, when the API processing fails, it returns the standard error response.

| **Element Name** | **Data Type** | **Data Size** | **Description**  |
| ---------------- | ------------- | ------------- | ---------------- |
| code             | String        | -             | Response code    |
| message          | String        | -             | Response message |
| result           | Object        | -             | <p><br></p>      |

*   **Example :**&#x20;

    ```json
    HTTP/1.1 200 OK
    Content-type: application/json;charset=UTF-8
    {
        "result" : {
            "code" : "Success",
            "message" : "Request has been completed successfully."
        }
    }
    ```

### reactiveRecurringPurchase (Request to cancel the automatic payment cancellation)  <a href="#onestoreiapserverapi-apiv7-reactiverecurringpurchase-requesttocanceltheautomaticpaymentcancellation" id="onestoreiapserverapi-apiv7-reactiverecurringpurchase-requesttocanceltheautomaticpaymentcancellation"></a>

* **Desc :** Cancels the request for the cancellation of automatic payment of Monthly auto-renewal product. If using the purchaseToken of a subscription product, a 'NoSuchData' response is sent.
* **URI :** /v7/apps/{clientId}/purchases/auto/products/{productId}/{purchaseToken}/reactivate
* **Method :** POST
* **Request Parameter :** Path Variable format
  * String clientId : Client ID of the app that calls API (Data Size : 128)
  * String productId : Product ID (Data Size : 150)
  * String purchaseToken : Purchase token (Data Size : 20)
*   **Request Header:**&#x20;

    | Parameter Name | Data Type | Required | Description                                           |
    | -------------- | --------- | -------- | ----------------------------------------------------- |
    | Authorization  | String    | true     | The access\_token issued through the Access Token API |
    | Content-Type   | String    | true     | application/json                                      |
    | x-market-code  | String    | false    | Market classification code                            |
*   **Example**&#x20;

    ```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 :** N/A
* **Response Body :** JSON format\
  The response is returned in the following format to allow for a more intuitive determination of the process completion when API processing is successful. However, when the API processing fails, it returns the standard error response.

| **Element Name** | **Data Type** | **Data Size** | **Description**  |
| ---------------- | ------------- | ------------- | ---------------- |
| code             | String        | -             | Response code    |
| message          | String        | -             | Response message |
| result           | Object        | -             | <p><br></p>      |

*   **Example :**&#x20;

    <pre class="language-json"><code class="lang-json"><strong>HTTP/1.1 200 OK
    </strong>Content-type: application/json;charset=UTF-8
    {
        "result" : {
            "code" : "Success",
            "message" : "Request has been completed successfully."
        }
    }
    </code></pre>

### getVoidedPurchases (Check purchase cancellation details)  <a href="#onestoreiapserverapi-apiv7-getvoidedpurchases-checkpurchasecancellationdetails" id="onestoreiapserverapi-apiv7-getvoidedpurchases-checkpurchasecancellationdetails"></a>

* **Desc :** Checks the purchase cancellation details.
* **URI :** /v7/apps/{clientId}/voided-purchases
* **Method :** GET
* **Request Parameter :** Path Variable format
  * String clientId : Client ID of the app that calls API (Data Size : 128)
* **Request Parameter (Optional) :** Query String format
  * String continuationKey: The ONE store server returns this value if there are numerous purchase cancellations.If there is a continuationKey in the response, call getVoidedPurchases again. If there is continuationKey in the response, you can receive additional purchase cancellation histories if you call up getVoidedPurchases again and send continuationKey (data size: 41).
  * String startTime: The search start time of purchase cancellation date (milliseconds).The start time can be set until only one month prior to the current time, and if startTime is used alone, endTime will be set until one month after startTime (data size: 13).
  * String endTime : The search end time of purchase cancellation date (milliseconds).The end time cannot be bigger than the current time, and if endTime is used alone, the startTime will be set until one month prior to endTime.
  * unsigned integer maxResults : The default maximum number of searches is 100 (Data Size : 3)
*   **Request Header:**&#x20;

    | Parameter Name | Data Type | Required | Description                                           |
    | -------------- | --------- | -------- | ----------------------------------------------------- |
    | Authorization  | String    | true     | The access\_token issued through the Access Token API |
    | Content-Type   | String    | true     | application/json                                      |
    | x-market-code  | String    | false    | Market classification code                            |
*   **Example**&#x20;

    ```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 :** N/A
*   **Response Body :**

    | **Element Name**    | **Data Type** | **Data Size** | **Description**                                                                                                                                                                                                        |
    | ------------------- | ------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | continuationKey     | String        | 41            | It returns when the number of purchase cancellations is higher than the maximum number of searches. After that, if you set and call continuationKey, which has been received upon request, you can search the history. |
    | voidedPurchaseList  | <p><br></p>   | -             | <p><br></p>                                                                                                                                                                                                            |
    | purchaseId          | String        | 20            | Purchase ID                                                                                                                                                                                                            |
    | purchaseTime        | Long          | 13            | Purchase time (ms)                                                                                                                                                                                                     |
    | voidedTime          | Long          | 13            | Purchase cancellation time (ms)                                                                                                                                                                                        |
    | purchaseToken       | String        | 20            | Purchase token                                                                                                                                                                                                         |
    | marketCode          | String        | -             | Market identification code                                                                                                                                                                                             |
*   **Example :**&#x20;

    ```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"
            }
        ]
    }
    ```

### getSubscriptionDetail (Check subscription details)  <a href="#onestoreiapserverapi-apiv7-getsubscriptiondetail-checksubscriptiondetails" id="onestoreiapserverapi-apiv7-getsubscriptiondetail-checksubscriptiondetails"></a>

* **Desc :** Check detailed information of subscriptions.
* **URI :** /v7/apps/{clientId}/purchases/subscription/products/{productId}/{purchaseToken}
* **Method :** GET
* **Request Parameter :** Path Variable format
  * String clientId : Client ID of the app that calls API (Data Size : 128)
  * String productId : Product ID (Data Size : 150)
  * String purchaseToken : Purchase token (Data Size : 20)
*   **Request Header:**&#x20;

    | Parameter Name | Data Type | Required | Description                                           |
    | -------------- | --------- | -------- | ----------------------------------------------------- |
    | Authorization  | String    | true     | The access\_token issued through the Access Token API |
    | Content-Type   | String    | true     | application/json                                      |
    | x-market-code  | String    | false    | Market classification code                            |
*   **Example**&#x20;

    ```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 :** N/A
*   **Response Body :**

    <table data-header-hidden><thead><tr><th></th><th></th><th></th><th></th></tr></thead><tbody><tr><td>Element Name</td><td>Data Type</td><td>Data Size</td><td>Description</td></tr><tr><td>acknowledgementState</td><td>Integer</td><td>1</td><td>Purchase acknowledgement status (0: not acknowledged, 1: acknowledged)</td></tr><tr><td>developerPayload</td><td>String</td><td>200</td><td>Unique billing identifier provided by the developer</td></tr><tr><td>autoRenewing</td><td>boolean</td><td>-</td><td><p>Renewal status of next payment<br></p><ul><li>Request for cancellation, cancellation, expiration : false</li><li>Remaining : true</li></ul></td></tr><tr><td>paymentState</td><td>Integer</td><td>1</td><td><p>Subscription payment status</p><ul><li>null: Expired</li><li>0: Payment not completed</li><li>1: Payment completed after payment request</li><li>2: Processed as a free period</li><li>3: Processed as DFERRED option during product upgrade/downgrade</li></ul></td></tr><tr><td>priceAmount</td><td>String</td><td>-</td><td>Price</td></tr><tr><td>priceAmountMicros</td><td>Long</td><td>-</td><td>Price * 1 million</td></tr><tr><td>nextPriceAmount</td><td>String</td><td>-</td><td>Next purchase price</td></tr><tr><td>nextPriceAmountMicros</td><td>Long</td><td>-</td><td>Next purchase price * 1 million</td></tr><tr><td>nextPaymentTimeMillis</td><td>Long</td><td>13</td><td>Time of next purchase (ms)</td></tr><tr><td>priceCurrencyCode</td><td>String</td><td>-</td><td>Currency code (KRW fixed)</td></tr><tr><td>countryCode</td><td>String</td><td>-</td><td>Country code (KR fixed)</td></tr><tr><td>startTimeMillis</td><td>Long</td><td>13</td><td>Time of subscription start (first payment) (ms)</td></tr><tr><td>expiryTimeMillis</td><td>Long</td><td>13</td><td>Time of subscription expiration (ms)</td></tr><tr><td>pauseStartTimeMillis</td><td>Long</td><td>13</td><td>Subscription temporarily paused Pause start date (ms) - Only for subscriptions where reservation of pause or temporarily paused statuses exist</td></tr><tr><td>pauseEndTimeMillis</td><td>Long</td><td>13</td><td>Subscription temporarily paused Pause end date(ms) - Only for subscriptions where reservation of pause or temporarily paused statuses exist</td></tr><tr><td><pre><code>autoResumeTimeMillis
    </code></pre></td><td>Long</td><td>13</td><td><p>Re-subscription after temporary paused</p><ul><li>Normal subscription: null</li><li>Reservation/confirmation of pause, currently temporarily paused: Next payment date + Pause date</li></ul></td></tr><tr><td>linkedPurchaseToken</td><td>String</td><td>20</td><td>Previous purchaseToken when changing the subscription product - null, if not changed</td></tr><tr><td>lastPurchaseId</td><td>String</td><td>20</td><td>Last purchase ID</td></tr><tr><td>cancelledTimeMillis<br></td><td>Long</td><td>13</td><td>Time of subscription cancellation (ms)</td></tr><tr><td>cancelReason</td><td>Integer</td><td>1</td><td><p>Reason for cancellation </p><ul><li>0 : User request</li><li>1 : Other|</li></ul></td></tr><tr><td>promotionPrice</td><td>Object</td><td>-</td><td>Promotion price information</td></tr><tr><td>promotionPrice.promotionPrice</td><td>String</td><td>-</td><td>Promotion price</td></tr><tr><td>promotionPrice.promotionPriceMicros</td><td>Long</td><td>-</td><td>Promotion price information * 1 million</td></tr><tr><td>promotionPrice.promotionPeriod</td><td>Int</td><td>-</td><td>Promotion period</td></tr><tr><td>priceChange</td><td>Object</td><td>-</td><td>Details of price change</td></tr><tr><td>priceChange.seq</td><td>Integer</td><td>-</td><td>Price change sequence</td></tr><tr><td>priceChange.previousPrice</td><td>String</td><td>-</td><td>Previous price </td></tr><tr><td>priceChange.previousPriceMicros</td><td>Long</td><td>-</td><td>Previous price * 1 million</td></tr><tr><td>priceChange.newPrice</td><td>String</td><td>-</td><td>New price</td></tr><tr><td>priceChange.newPriceMicros</td><td>Long</td><td>-</td><td>New price * 1 million</td></tr><tr><td>priceChange.applyTimeMillis</td><td>Long</td><td>13</td><td>Time applied (ms)</td></tr><tr><td>priceChange.agreement</td><td>Boolean</td><td>-</td><td>Agreement to price change</td></tr><tr><td>priceChange.agreementDueDateTimeMillis</td><td>Long</td><td>13</td><td>Expiration time of agreement to price change (ms)<br>Value = price change date +7+30 days<br>Users can agree to the first automatic payment after the expiration date of agreement.</td></tr></tbody></table>
*   **Example :**&#x20;

    ```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 (Request to cancel subscription automatic payment)  <a href="#onestoreiapserverapi-apiv7-cancelsubscription-requesttocancelsubscriptionautomaticpayment" id="onestoreiapserverapi-apiv7-cancelsubscription-requesttocancelsubscriptionautomaticpayment"></a>

* **Desc :** Requests the cancellation of automatic payment of subscription products. However, if the subscription status is paused, payment is suspended, or the account is held at the time of request, immediate cancellation is requested.
* **URI :** /v7/apps/{clientId}/purchases/subscription/products/{productId}/{purchaseToken}/cancel
* **Method :** POST
* **Request Parameter :** Path Variable format
  * String clientId : Client ID of the app that calls API (Data Size : 128)
  * String productId : Product ID (Data Size : 150)
  * String purchaseToken : Purchase token (Data Size : 20)
*   **Request Header:**&#x20;

    | Parameter Name | Data Type | Required | Description                                           |
    | -------------- | --------- | -------- | ----------------------------------------------------- |
    | Authorization  | String    | true     | The access\_token issued through the Access Token API |
    | Content-Type   | String    | true     | application/json                                      |
    | x-market-code  | String    | false    | Market classification code                            |
*   **Example**&#x20;

    ```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 :** N/A
* **Response Body :** JSON format\
  The response is returned in the following format to allow for a more intuitive determination of the process completion when API processing is successful. However, when the API processing fails, it returns the standard error response.

| **Element Name** | **Data Type** | **Data Size** | **Description**  |
| ---------------- | ------------- | ------------- | ---------------- |
| code             | String        | -             | Response code    |
| message          | String        | -             | Response message |
| result           | Object        | -             | <p><br></p>      |

*   **Example :** &#x20;

    ```json
    HTTP/1.1 200 OK
    Content-type: application/json;charset=UTF-8
    {
        "result" : {
            "code" : "Success",
            "message" : "Request has been completed successfully."
        }
    }
    ```

### reactivateSubscription (Request to cancel the subscription automatic payment cancellation)  <a href="#onestoreiapserverapi-apiv7-reactivatesubscription-requesttocancelthesubscriptionautomaticpaymentcanc" id="onestoreiapserverapi-apiv7-reactivatesubscription-requesttocancelthesubscriptionautomaticpaymentcanc"></a>

* **Desc :** Cancels the request for the cancellation of automatic payment for subscription products. However, in the case immediate cancellation was done, the request for cancellation cannot be canceled.
* **URI :** /v7/apps/{clientId}/purchases/subscription/products/{productId}/{purchaseToken}/reactivate
* **Method :** POST
* **Request Parameter :** Path Variable format
  * String clientId : Client ID of the app that calls API (Data Size : 128)
  * String productId : Product ID (Data Size : 150)
  * String purchaseToken : Purchase token (Data Size : 20)
*   **Request Header:**&#x20;

    | Parameter Name | Data Type | Required | Description                                           |
    | -------------- | --------- | -------- | ----------------------------------------------------- |
    | Authorization  | String    | true     | The access\_token issued through the Access Token API |
    | Content-Type   | String    | true     | application/json                                      |
    | x-market-code  | String    | false    | Market classification code                            |
*   **Example**&#x20;

    ```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 :** N/A
* **Response Body :** JSON format

The response is returned in the following format to allow for a more intuitive determination of the process completion when API processing is successful. However, when the API processing fails, it returns the standard error response.

| **Element Name** | **Data Type** | **Data Size** | **Description**  |
| ---------------- | ------------- | ------------- | ---------------- |
| code             | String        | -             | Response code    |
| message          | String        | -             | Response message |
| result           | Object        | -             | <p><br></p>      |

*   **Example :**&#x20;

    <pre class="language-json"><code class="lang-json"><strong>HTTP/1.1 200 OK
    </strong>Content-type: application/json;charset=UTF-8
    {
        "result" : {
            "code" : "Success",
            "message" : "Request has been completed successfully."
        }
    }
    </code></pre>

### deferSubscription (Request for subscription payment extension)  <a href="#onestoreiapserverapi-apiv7-defersubscription-requestforsubscriptionpaymentextension" id="onestoreiapserverapi-apiv7-defersubscription-requestforsubscriptionpaymentextension"></a>

* **Desc :** The next payment date for subscription products is deferred.
* **URI :** /v7/apps/{clientId}/purchases/subscription/products/{productId}/{purchaseToken}/defer
* **Method :** POST
* **Request Parameter :** Path Variable format
  * String clientId : Client ID of the app that calls API (Data Size : 128)
  * String productId : Product ID (Data Size : 150)
  * String purchaseToken : Purchase token (Data Size : 20)
*   **Request Header:**&#x20;

    | Parameter Name | Data Type | Required | Description                                           |
    | -------------- | --------- | -------- | ----------------------------------------------------- |
    | Authorization  | String    | true     | The access\_token issued through the Access Token API |
    | Content-Type   | String    | true     | application/json                                      |
    | x-market-code  | String    | false    | Market classification code                            |
*   **Example**&#x20;

    ```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 format

    | **Parameter Name** | **Data Type** | **Required** | **Description**                                                                               |
    | ------------------ | ------------- | ------------ | --------------------------------------------------------------------------------------------- |
    | deferPeriod        | Integer       | true         | <p>Extension period </p><ul><li>Commercial: Daily (1-365)</li><li>Sandbox: Minutes|</li></ul> |
*   **Example :**&#x20;

    ```json
    Content-type: application/json;charset=UTF-8
    {
    	"deferPeriod" : 3
    }
    ```
* **Response Body :** JSON format\
  The response is returned in the following format to allow for a more intuitive determination of the process completion when API processing is successful. However, when the API processing fails, it returns the standard error response.

| **Element Name** | **Data Type** | **Data Size** | **Description**  |
| ---------------- | ------------- | ------------- | ---------------- |
| code             | String        | -             | Response code    |
| message          | String        | -             | Response message |
| result           | Object        | -             | <p><br></p>      |

*   **Example :**&#x20;

    ```json
    HTTP/1.1 200 OK
    Content-type: application/json;charset=UTF-8
    {
        "result" : {
            "code" : "Success",
            "message" : "Request has been completed successfully."
        }
    }
    ```

## Standard Response Specifications <a href="#onestoreiapserverapi-apiv7-standardresponsespecifications" id="onestoreiapserverapi-apiv7-standardresponsespecifications"></a>

### Standard Response Code <a href="#onestoreiapserverapi-apiv7-standardresponsecode" id="onestoreiapserverapi-apiv7-standardresponsecode"></a>

| **Code**                   | **Message**                                                                           | **Description**                                                                       | **HTTP Status Code**                  | **Target API**                                                                       |
| -------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------ |
| AccessBlocked              | The request was blocked.                                                              | The request was blocked.                                                              | 403 - Forbidden                       | Common                                                                               |
| AccessTokenExpired         | Access token has expired.                                                             | Access token has expired.                                                             | 401 - Unauthorized                    | Common                                                                               |
| BadRequest                 | The request is invalid.                                                               | The request is invalid.                                                               | 400 - Bad Request                     | Common                                                                               |
| DeveloperPayloadNotMatch   | The request developerPayload does not match the value passed in the purchase request. | The request developerPayload does not match the value passed in the purchase request. | 400 - Bad Request                     | acknowledgePurchaseconsumePurchase                                                   |
| InternalError              | An undefined error has occurred.                                                      | An undefined error has occurred.                                                      | 500 - Internal Server Error           | Common                                                                               |
| InvalidAccessToken         | Access token is invalid.                                                              | Access token is invalid.                                                              | 401 - Unauthorized                    | Common                                                                               |
| InvalidAuthorizationHeader | Authorization header is invalid.                                                      | Authorization header is invalid.                                                      | 400 - Bad Request                     | Common                                                                               |
| InvalidConsumeState        | The purchase consumption status cannot be changed or has already been changed.        | The purchase consumption status cannot be changed or has already been changed.        | 409 - Conflict                        | consumePurchase                                                                      |
| InvalidContentType         | The request content-type is invalid.                                                  | The request content-type is invalid.                                                  | 415 - Unsupported Media Type          | Common                                                                               |
| InvalidPurchaseState       | Purchase history does not exist or is not completed.                                  | Purchase history does not exist or is not completed.                                  | 409 - Conflict                        | acknowledgePurchaseconsumePurchase                                                   |
| InvalidRequest             | Request parameters are invalid. \[ field1, field2, ... ]                              | Request parameters are invalid. \[ field1, field2, ... ]                              | 400 - Bad Request                     | Common                                                                               |
| MethodNotAllowed           | HTTP method not supported.                                                            | HTTP method not supported.                                                            | 405 - Method Not Allowed              | Common                                                                               |
| NoSuchData                 | The requested data could not be found.                                                | The requested data could not be found.                                                | 404 - Not Found                       | getPurchaseDetailsgetRecurringPurchaseDetails                                        |
| RequiredValueNotExist      | Request parameters are required. \[ field1, field2, ... ]                             | Request parameters are required. \[ field1, field2, ... ]                             | 400 - Bad Request                     | Common                                                                               |
| ResourceNotFound           | The requested resource could not be found.                                            | The requested resource could not be found.                                            | 404 - Not Found                       | Common                                                                               |
| ServiceMaintenance         | System maintenance is in progress.                                                    | System maintenance is in progress.                                                    | 503 - Service Temporarily Unavailable | Common                                                                               |
| Success                    | The request has been completed successfully.                                          | The request has been completed successfully.                                          | 200 - Success                         | acknowledgePurchaseconsumePurchasecancelRecurringPurchasereactivateRecurringPurchase |
| UnauthorizedAccess         | Not authorized to access this API.                                                    | Not authorized to access this API.                                                    | 403 - Forbidden                       | Common                                                                               |

\


### Standard Error Response Specifications <a href="#onestoreiapserverapi-apiv7-standarderrorresponsespecifications" id="onestoreiapserverapi-apiv7-standarderrorresponsespecifications"></a>

The Server API returns the standard error response in the same format as the example below when the error occurs other than the normal response. Refer to the following.

*   **Response Body :** JSON format

    | **Element Name** | **Data Type** | **Data Size** | **Description**  |
    | ---------------- | ------------- | ------------- | ---------------- |
    | code             | String        | -             | Response code    |
    | message          | String        | -             | Response message |
    | error            | Object        | -             | <p><br></p>      |
*   **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."
        }
    }
    ```

## Common Code <a href="#onestoreiapserverapi-apiv7-commoncode" id="onestoreiapserverapi-apiv7-commoncode"></a>

### In-app Type Code <a href="#onestoreiapserverapi-apiv7-in-apptypecode" id="onestoreiapserverapi-apiv7-in-apptypecode"></a>

| **Code**     | **Name**                     | **Description**                                   |
| ------------ | ---------------------------- | ------------------------------------------------- |
| inapp        | Managed product              | Consumable/non-consumable/non-renewable products  |
| auto         | Monthly auto-renewal product | Monthly auto-renewal (automatic payment) products |
| subscription | Subscription product         | Subscription (automatic payment) products         |
| all          | All in-apps                  | Managed product + Monthly auto-renewal products   |
