# In-App Purchase Server API
ONE store In-App Purchase (IAP) API indicates an Open API, which offers to developers data for the in-app products paid on ONE store.\
OAuth authentication is required to use this Open API.
### **HOST URL**
* ### The {host} URL in this document is below :
| ONE store environment | Host URL |
| --------------------- | --------------------------------------------------- |
| Sandbox(Development) | [sbpp.onestore.co.kr](https://sbpp.onestore.co.kr/) |
| commercial | [apis.onestore.co.kr](https://apis.onestore.co.kr/) |
### **OAuth v2 Overview**
* #### **ONE store OAuth**
* OAuth authentication is required for the interworking with ONE store Server Open API.
* Understanding of ONE store OAuth v2
* Access Token is a value that can be issued through ONE store Server Open API. It is used as an authentication value when calling Server Open API offered by ONE store.
* Access Token will be valid for 3,600 seconds on default. When it expires or its time of expiration is less than 600 seconds, you can get a new token issued by calling getAccessToken()
* It is still available to use the existing Access Token until its validity expires.
* This issuance method is used for numerous Access Tokens, and therefore it can become a form that allows the acquisition and use of Access Tokens, which vary depending on each service interface of developers.
* * * A typical interworking flow is as follows:
* * * * If authentication error occurs while calling API, you can call the process of acquiring Access Token (no. 1).
* To call ONE store Server Open API, use the Authorization Bearer scheme. Calling sample is as follows:
* * * * | `GET /api/purchase/details/SANDBOX3000120004476/com.onestore.game.goindol HTTP/1.1Host: sbpp.onestore.co.krAuthorization: Bearer 680b3621-1234-1234-1234-8adfaef561b4` |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
* The Authorization header should contain Bearer + Space + AccessToken case sensitive as shown in the example above
* The value of Bearer is an Access Token value, which is issued by calling getAccessToken().
* * * * * Wrong examples
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**
* Issue AccessToken
* URI: https\://{host}/v2/oauth/token
* Method: POST, PUT
* Request Header
| **Parameter Name** | **Description** | **Example** |
| ------------------ | -------------------------------------------------------------------------------------- | ----------------------------------------------- |
| Content-Type | When Http is requested, application/x-www-form-urlencoded must be set as Content Type. | Content-Type: application/x-www-form-urlencoded |
\
**Parameter**
| **Parameter Name** | **Description** | **Example** |
| ------------------ | ------------------------------------------------------------------------------------------ | -------------------------------------------- |
| client\_id | In general, it is the same as packageName. | com.onestore.game.goindol |
| client\_secret | It is a client secret value, which is issued when an app is registered on Developer Center | vxIMAGcVz3DAx20uDBr/IDWNJAPNHFl7YruF4uxB6BI= |
| grant\_type | It is a fixed value. | client\_credentials |
\
**Response Body : JSON format**
| **Element Name** | **Data Type** | **Data Size** | **Description** |
| ---------------- | ------------- | ------------- | ------------------------------------ |
| status | String | 7 | The result of issuing Access Token |
| client\_id | String | 255 | OAuth authentication client\_id |
| access\_token | String | 36 |
|
| token\_type | String | 6 | Provides bearer method only |
| expires\_in | Integer | 10 | Token expiration time, unit: seconds |
| scope | String | 1024 | Token use range |
Request Example
| 12345 | `POST /v2/oauth/token HTTP/1.1Host: apis.onestore.comContent-Type: application/x-www-form-urlencoded;charset=UTF-8` `grant_type=client_credentials&client_id=com.onestore.game.goindol&client_secret=vxIMAGcVz3DAx20uDBr/IDWNJAPNHFl7YruF4uxB6BI=` |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Response Example
| 12345678 | `{ "status":"SUCCESS", "client_id":"com.onestore.game.goindol", "access_token":"680b3621-1234-1234-1234-8adfaef561b4", "token_type":"bearer", "expires_in":3010, "scope":"DEFAULT"}` |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
* #### **Example of Issuing Access Token**
* This is a sample for the issuance of Access Token by using curl.
| 123456789101112131415161718 | `curl -v -X POST -H "Content-Type: application/x-www-form-urlencoded"` `https://sbpp.onestore.co.kr/v2/oauth/token -d "grant_type=client_credentials" -d "client_id=com.onestore.game.goindol" -d "client_secret=vxIMAGcVz3DAx20uDBr/IDWNJAPNHFl7YruF4uxB6BI="> POST /v2/oauth/token HTTP/1.1> Host: sbpp.onestore.co.kr> 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{"status":"SUCCESS","client_id":"com.onestore.game.goindol","access_token":"680b3621-1234-1234-1234-8adfaef561b4","token_type":"bearer","expires_in":3600,"scope":"DEFAULT"}` |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
AccessToken in the sandbox (development) and commercial environments are managed independently,\
so you have to manage them separately by environment.
### **Server API Details**
* #### getPurchaseDetails (Check Purchased In-App Product Details)
* Desc: check the details of the purchased in-app products.
* URI: https\://{host}/v2/purchase/details/{purchaseId}/{packageName}
* Method: GET
* Parameters:
* String packageName : the package name of the app which calls the API (Data Size : 128)
* String purchaseId : the purchase ID (Data Size : 20)
* **Request Header**
| Parameter Name | Data Type | Required | Description |
| -------------- | --------- | -------- | ------------------------------------------------------- |
| Authorization | String | true | It is the access-token issued through Access Token API. |
| Content-Type | String | true | application/json |
Example
| 123 | `Request.setHeader("Authorization", " Bearer ");Request.setHeader("Content-Type", "application/json");` |
| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
\
**Request Body**: NA
**Response Body**:
| **Element Name** | **Data Type** | **Data Size** | **Required** | **Description** |
| ---------------- | ------------- | ------------- | ------------ | ---------------------------------------------------------------------------------------- |
| consumptionState | Interger | 1 | true | The consumption status of the purchased in-app products (0 : not-consumed, 1 : consumed) |
| developerPayload | String | 200 | true | The payment unique identifier that is provided by the developer |
| purchaseState | Interger | 1 | true | The consumption status (0 : purchased, 1 : cancelled) |
| purchaseTime | Integer | 13 | true | The purchase time (ms) |
Example
| 123456 | `{ "consumptionState": 0, "developerPayload": "developerPayload", "purchaseState": 0, "purchaseTime": 1345678900000}` |
| ------ | ------------------------------------------------------------------------------------------------------------------------- |
* #### **getPurchaseDetailsByProductId (Check Purchased In-App Product Details)**
* Desc: This allows to check the details of purchased in-app products. It has a stronger security feature since it makes a response after confirming if the purchase of the in-app product in question (productId) is valid.
* URI: https\://{host}/v2/purchase/details-by-productid/{purchaseId}/{packageName}/{productId}
* Method: GET
* Parameters:
* String packageName : the package name of the app which calls the API (Data Size : 128)
* String purchaseId : the purchase ID (Data Size : 20)
* String productId : the product ID (Data Size : 150)
* **Request Header**
| **Parameter Name** | **Data Type** | **Required** | **Description** |
| ------------------ | ------------- | ------------ | ------------------------------------------------------- |
| Authorization | String | true | It is the access-token issued through Access Token API. |
| Content-Type | String | true | application/json |
Example
| 123 | `Request.setHeader("Authorization", " Bearer ");Request.setHeader("Content-Type", "application/json");` |
| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
\
**Request Body**: NA
**Response Body**:
| Element Name | Data Type | Data Size | Required | Description |
| ---------------- | --------- | --------- | -------- | -------------------------------------------------------------------------------------- |
| consumptionState | Integer | 1 | true | The status of the consumption of the purchased product (0 :not consumed, 1 : consumed) |
| developerPayload | String | 200 | true | The unique payment identifier provided by the developer |
| purchaseState | Integer | 1 | true | The status of purchase (0 : purchased, 1 :cancelled) |
| purchaseTime | Integer | 13 | true | The time of purchase (ms) |
Example
| 123456 | `{ "consumptionState": 0, "developerPayload": "developerPayload", "purchaseState": 0, "purchaseTime": 1345678900000}` |
| ------ | ------------------------------------------------------------------------------------------------------------------------- |
* #### **getRecurringPurchaseDetails (Check Purchased In-App Product Details)**
* Desc: Based on purchase ID, check the details of the purchased subscription
* URI: https\://{host}/v2/purchase/recurring-details/{purchaseId}/{packageName}
* Method: GET
* Parameters:
* String packageName : the package name of the app which calls the API (Data Size : 128)
* String purchaseId : the purchase ID (Data Size : 20)
* Request Header
| Parameter Name | Data Type | Required | Description |
| -------------- | --------- | -------- | ------------------------------------------------------- |
| Authorization | String | true | It is the access-token issued through Access Token API. |
| Content-Type | String | true | application/json |
Example
| 123 | `Request.setHeader("Authorization", " Bearer ");Request.setHeader("Content-Type", "application/json");` |
| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
\
**Request Body**: NA
**Response Body**:
| **Element Name** | **Data Type** | **Data Size** | **Required** | **Description** |
| ---------------- | ------------- | ------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------- |
| startTime | Interger | 13 | true | The start date of the purchased in-app product(ms) |
| expiryTime | Integer | 13 | true | The expiration date of the purchased in-app product(ms) |
| nextPaymentTime | Interger | 13 | false | The date and time of the next automatic payment |
| autoRenewing | boolean | - | true | Whether the automatic payment is made after the use end date (expiryTime) |
| price | Integer | - | true | The in-app product price |
| developerPayload | String | 200 | false | The payment unique identifier that is provided by the developer |
| purchaseState | Integer | 1 | true | The purchase status (0 : purchased, 1 : cancelled) |
| cancelReason | String | 1 | flase | Reason for cancellation (0 : cancellation at the request of the customer, 1 : cancellation by other system processing ) |
| cancelledTime | Integer | 13 | false | The cancellation time(ms) |
Example
| 1234567891011 | `{ "startTime": 1345678900000, "expiryTime": 1345678999999, "nextPaymentTime": 1345688000000, "autoRenewing": true, "price": 50000 "developerPayload": "8ce0dc420c9dd244580a", "purchaseState": 0, "cancelReason": 1, "cancelledTime": 1345679000000}` |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
* #### **getLastRecurringPurchaseDetails (Check Purchased Subscription Details)**
* Desc: This allows to check the details of purchased in-app products. It has a stronger security feature since it makes a response after confirming if the purchase of the in-app product in question (productId) is valid.
* URI: https\://{host}/v2/purchase/last-recurring-details/{purchaseId}/{packageName}
* Method: GET
* Parameters:
* String packageName : the package name of the app which calls the API (Data Size : 128)
* String purchaseId : the purchase ID (Data Size : 20)
* Request Header
| Parameter Name | Data Type | Required | Description |
| -------------- | --------- | -------- | ------------------------------------------------------- |
| Authorization | String | true | It is the access-token issued through Access Token API. |
| Content-Type | String | true | application/json |
Example
| 123 | `Request.setHeader("Authorization", " Bearer ");Request.setHeader("Content-Type", "application/json");` |
| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
\
**Request Body**: NA
**Response Body**:
| **Element Name** | **Data Type** | **Data Size** | **Required** | **Description** |
| ---------------- | ------------- | ------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------- |
| startTime | Interger | 13 | true | The start date of the purchased in-app product(ms) |
| expiryTime | Integer | 13 | true | The expiration date of the purchased in-app product(ms) |
| nextPaymentTime | Interger | 13 | false | The date and time of the next automatic payment |
| autoRenewing | boolean | - | true | Whether the automatic payment is made after the use end date (expiryTime) |
| price | Integer | - | true | The in-app product price |
| developerPayload | String | 200 | false | The payment unique identifier that is provided by the developer |
| purchaseState | Integer | 1 | true | The purchase status (0 : purchased, 1 : cancelled) |
| cancelReason | String | 1 | flase | Reason for cancellation (0 : cancellation at the request of the customer, 1 : cancellation by other system processing ) |
| cancelledTime | Integer | 13 | false | The cancellation time(ms) |
Example
| 123456789 | `{ "startTime": 1345678900000, "expiryTime": 1345678999999, "nextPaymentTime": 1345688000000, "autoRenewing": true, "cancelReason": 1, "cancelledTime": 1345679000000, "lastPurchaseId":"15081718460701027851"}` |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
* #### **manageRecurringPaymentStatus (Cancel Automatic Payment/Cancel the Cancellation)**
* Desc: change the status of the subscription(cancel & cancel the cancellation).
* URI: https\://{host}/v2/purchase/manage-payment-status/{purchaseId}/{packageName}/{action}
* Method: POST
* Parameters:
* String packageName : the package name of the app which calls the API (Data Size : 128)
* String purchaseId : the purchase ID (Data Size : 20)
* String action: the status change type; cancel(cancel the subscription) and reactivate(cancel the cancellation of the subscription) (Data Size : 10)
* **Request Header**
| Parameter Name | Data Type | Required | Description |
| -------------- | --------- | -------- | ------------------------------------------------------- |
| Authorization | String | true | It is the access-token issued through Access Token API. |
| Content-Type | String | true | application/json |
Example
| 123 | `Request.setHeader("Authorization", " Bearer ");Request.setHeader("Content-Type", "application/json");` |
| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
\
**Request Body**: NA
**Response Body**:
| Element Name | Data Type | Data Size | Required | Description |
| ------------ | --------- | --------- | -------- | --------------------------------------------------------------- |
| responseCode | Integer | 1 | true | Whether the status change is success (0 : success, 1 : failure) |
| purchaseId | String | 20 | true | The purchase ID |
Example
| 1234 | `{ "responseCode": 0, "purchaseId"` `: "17103013155810111392"}` |
| ---- | ----------------------------------------------------------------- |
* **getVoidedPurchases (Check Purchase Cancellation Details)**
* Desc: check the details of the purchase cancellation
* URI: https\://{host}/v2/purchase/voided-purchases/{packageName}
* Method: GET
* Parameters:
* String packageName : the package name of the app which calls the API (Data Size : 128)
* Optional Query Parameters :
* String continuationKey : When a user has many cancelled purchases for the application in query, getVoidedPurchases returns this response value. If there is the continuationKey in the response, it is required to separately call the getVoidedPurchases again with the continuationKey which is received as the response to get more cancelled purchases. (Data Size : 41)
* String startTime : it is the start date of searching the cancellations that you want to check (milliseconds). It is available to search up to the past 30 days from the current time. If the startTime is used alone, the endTime will be set at the date one month after the startTime. (Data Size : 13)
* String endTime : it is the end date of searching the cancellations that you want to check (milliseconds). It is not available to search the end date which is after the current time. If the endTime is used alone, the startTime will be set at the date one month before the endTime. (Data Size : 13)
* unsigned integer maxResults : the maximum number of views (default 100) (Data Size : 3)
* Request Header
| Parameter Name | Data Type | Required | Description |
| -------------- | --------- | -------- | ------------------------------------------------------- |
| Authorization | String | true | It is the access-token issued through Access Token API. |
| Content-Type | String | true | application/json |
Example
| 123 | `Request.setHeader("Authorization", " Bearer ");Request.setHeader("Content-Type", "application/json");` |
| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
\
**Request Body**: NA
**Response Body**:
| Element Name | Data Type | Data Size | Required | Description | |
| ------------------ | ------------ | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| continuationKey | String | 41 | false | When a user has many cancelled purchases for the application in query, getVoidedPurchases returns this response value. If there is the continuationKey in the response, it is required to separately call the getVoidedPurchases again with the continuationKey which is received as the response to get more cancelled purchases. | |
| voidedPurchaseList | Object | - | true | The purchase cancellation information | |
|
| purchaseId | String | 20 | true | The purchase number |
|
| purchaseTime | Integer | 13 | true | The purchase time(ms) |
|
| voidedTime | Integer | 13 | true | The purchase cancellation time(ms) |
Example
| 123456789101112131415 | `{ "continuationKey": "continuationKey", "voidedPurchaseList": [ { "purchaseId"` `: "17103009124410111299", "purchaseTime"` `: 1345678900000, "voidedTime"` `: 1345678910000 }, { "purchaseId"` `: "17103009140030111301", "purchaseTime"` `: 1345678930000, "voidedTime"` `: 1345678940000 } ]}` |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
* **consumePurchase (Consume Purchased In-App Products)**
* * Desc: convert the purchased in-app product status into the consumed status.
* URI: https\://{host}/v2/purchase/consume/{purchaseId}/{packageName}
* Method: POST
* Parameters:
* String packageName : the package name of the app which calls the API (Data Size : 128)
* String purchaseId : the purchase ID (Data Size : 20)
* Request Header
| Parameter Name | Data Type | Required | Description |
| -------------- | --------- | -------- | ------------------------------------------------------- |
| Authorization | String | true | It is the access-token issued through Access Token API. |
| Content-Type | String | true | application/json |
Example
| 123 | `Request.setHeader("Authorization", " Bearer ");Request.setHeader("Content-Type", "application/json");` |
| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
\
**Request Body**: NA
**Response Body**:
| Element Name | Data Type | Data Size | Required | Description |
| ---------------- | --------- | --------- | -------- | ------------------------------------------------------- |
| consumptionState | Integer | 1 | true | The consumption status (0 : not consumed, 1 : consumed) |
| purchaseId | String | 20 | true | The purchase ID |
Example
| 1234 | `{ "consumptionState": 0, "purchaseId"` `: "17103013155810111392"}` |
| ---- | --------------------------------------------------------------------- |
### **Error Response**
* The Server API makes separate responses in JSON format when an error occurs besides normal responses. Please refer to the followings. \
* #### Response Body : JSON format
| Element Name | Data Type | Description | |
| ------------ | --------- | --------------------- | ----------------- |
| error | Object | The error information | |
|
| code | Integer | The error code |
|
| message | String | The error message |
**Error Codes**
| Classification | Code | Message |
| ----------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Common | 9000 | The required value does not exist. |
| 9001 | The checked result value does not exist. | |
| 9999 | An undefined error occurs. | |
| 401 | Token has expired. | |
| getVoidedPurchase | 9100 | The package name is not valid. |
| 9101 | Check the search condition rules. | |
| consumePurchase | 9200 | The purchase history does not exist, or the purchase is not completed. |
| 9201 | It is not available to change the consumption status, or the change is already completed. | |
| 9202 | There are more than 2 purchases whose consumption status will be changed. | |
| Issue AccessToken | 400 | Invalid token request. |