ONE store IAP Server API (API V7)
Last updated
Last updated
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.
The Host Domain used in this document is as follows:
ONE store Environment | Host Domain |
---|---|
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)
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>
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
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.
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
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. \
'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
Check client_id & client_secret
You can check the client_id and client_secret values by clicking on the 'Credentials' button on the 'In-App' of the app registered on the ONE store Developer Center.
URI : /v7/oauth/token
Method: POST
Request Parameter: Form format
Request Header :
Example
Response Body: JSON format
Example:
Example of issuance:
AccessToken in the review (development) and commercial environments is managed independently, and therefore you must manage AccessToken separately per environment.
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/{packageName}/purchases/inapp/products/{productId}/{purchaseToken}
Method : GET
Request Parameter : Path Variable format
String packageName : Package name 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:
Example
Request Body : N/A
Response Body : JSON format
Example:
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/{packageName}/purchases/auto/products/{productId}/{purchaseToken}
Method : GET
Request Parameter : Path Variable format
String packageName : Package name 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:
Example
Request Body : N/A
Response Body : JSON format
Example :
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
Desc : Changes the status of purchased managed product or monthly auto-renewal product into the 'acknowledged' status.
URI : https://{host}/v7/apps/{packageName}/purchases/all/products/{productId}/{purchaseToken}/acknowledge
Method : POST
Request Parameter : Path Variable format
String packageName : Package name 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:
Example
Response Body : JSON forat
Example :
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.
Example :
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.
Desc : Changes the status of purchased Managed product into the 'consumed' status.
URI : /v7/apps/{packageName}/purchases/inapp/products/{productId}/{purchaseToken}/consume
Method : POST
Request Parameter : Path Variable format
String packageName : Package name 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:
Example
Request Body : JSON format
Example :
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.
Example :
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/{packageName}/purchases/auto/products/{productId}/{purchaseToken}/cancel
Method : POST
Request Parameter : Path Variable format
String packageName : Package name 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:
Example
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.
Example :
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/{packageName}/purchases/auto/products/{productId}/{purchaseToken}/reactivate
Method : POST
Request Parameter : Path Variable format
String packageName : Package name 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:
Example
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.
Example :
Desc : Checks the purchase cancellation details.
URI : /v7/apps/{packageName}/voided-purchases
Method : GET
Request Parameter : Path Variable format
String packageName : Package name 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:
Example
Request Body : N/A
Response Body :
Example :
Desc : Check detailed information of subscriptions.
URI : /v7/apps/{packageName}/purchases/subscription/products/{productId}/{purchaseToken}
Method : GET
Request Parameter : Path Variable format
String packageName : Package name 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:
Example
Request Body : N/A
Response Body :
Example :
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/{packageName}/purchases/subscription/products/{productId}/{purchaseToken}/cancel
Method : POST
Request Parameter : Path Variable format
String packageName : Package name 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:
Example
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.
Example :
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/{packageName}/purchases/subscription/products/{productId}/{purchaseToken}/reactivate
Method : POST
Request Parameter : Path Variable format
String packageName : Package name 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:
Example
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.
Example :
Desc : The next payment date for subscription products is deferred.
URI : /v7/apps/{packageName}/purchases/subscription/products/{productId}/{purchaseToken}/defer
Method : POST
Request Parameter : Path Variable format
String packageName : Package name 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:
Example
Request Body : JSON format
Example :
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.
Example :
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
Example
Market Code | Service Country |
---|---|
Parameter Name | Data Type | Required | Description |
---|---|---|---|
Parameter Name | Data Type | Required | Description |
---|---|---|---|
Parameter Name | Data Type | Required | Description |
---|---|---|---|
Parameter Name | Data Type | Required | Description |
---|---|---|---|
Parameter Name | Data Type | Required | Description |
---|---|---|---|
Parameter Name | Data Type | Required | Description |
---|---|---|---|
Parameter Name | Data Type | Required | Description |
---|---|---|---|
Parameter Name | Data Type | Required | Description |
---|---|---|---|
Parameter Name | Data Type | Required | Description |
---|---|---|---|
Parameter Name | Data Type | Required | Description |
---|---|---|---|
Parameter Name | Data Type | Required | Description |
---|---|---|---|