English
Search
K

ONE store IAP Server API (API V7)

Overview

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

The Host Domain used in this document is as follows:
ONE store Environment
Host Domain
Sandbox (development)
Commercial
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)

Market Classification

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

ONE store OAuth

OAuth Overview

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. \
GET /v7/apps/com.onestore.game.goindol/purchases/inapp/products/product01/SANDBOXT000120004476 HTTP/1.1
Host: sbpp.onestore.co.kr
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

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.

Issue AccessToken

  • URI : /v7/oauth/token
  • Method: POST
  • Request Parameter: Form format
    Parameter Name
    Description
    Example
    client_id
    Typically the same as packageName
    com.onestore.game.goindol
    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 :
    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
    x-market-code: MKT_GLB
  • Example
    POST /v7/oauth/token HTTP/1.1
    Host: apis.onestore.com
    Content-Type: application/x-www-form-urlencoded;charset=UTF-8
    x-market-code: MKT_GLB
    grant_type=client_credentials&client_id=com.onestore.game.goindol&client_secret=vxIMAGcVz3DAx20uDBr/IDWNJAPNHFl7YruF4uxB6BI=
  • Response Body: JSON 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:
    {
    "client_id":"com.onestore.game.goindol",
    "access_token":"680b3621-1234-1234-1234-8adfaef561b4",
    "token_type":"bearer",
    "expires_in":3010,
    "scope":"DEFAULT"
    }
  • Example of issuance:
    curl -v -X POST https://sbpp.onestore.co.kr/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=com.onestore.game.goindol" \
    -d "client_secret=vxIMAGcVz3DAx20uDBr/IDWNJAPNHFl7YruF4uxB6BI="
    > POST /v7/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
    {"client_id":"com.onestore.game.goindol","access_token":"680b3621-1234-1234-1234-8adfaef561b4","token_type":"bearer","expires_in":3600,"scope":"DEFAULT"}
    AccessToken in the review (development) and commercial environments is managed independently, and therefore you must manage AccessToken separately per environment.

Server API Details

getPurchaseDetails (Check purchased in-app product details)

  • 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:
    Parameter Name
    Data Type
    Required
    Description
    Authorization
    String
    true
    Access Token API를 통해 발급받은 access_token
    Content-Type
    String
    true
    application/json
    x-market-code
    String
    false
    마켓 구분 코드
  • Example
    Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4");
    Request.setHeader("Content-Type", "application/json");
    Request.setHeader("x-market-code", "MKT_GLB");
  • Request Body : 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:
    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)

  • 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:
    Parameter Name
    Data Type
    Required
    Description
    Authorization
    String
    true
    Access Token API를 통해 발급받은 access_token
    Content-Type
    String
    true
    application/json
    x-market-code
    String
    false
    마켓 구분 코드
  • Example
    Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4");
    Request.setHeader("Content-Type", "application/json");
    Request.setHeader("x-market-code", "MKT_GLB");
  • Request Body : 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 :
    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)

  • 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:
    Parameter Name
    Data Type
    Required
    Description
    Authorization
    String
    true
    Access Token API를 통해 발급받은 access_token
    Content-Type
    String
    true
    application/json
    x-market-code
    String
    false
    마켓 구분 코드
  • Example
    Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4");
    Request.setHeader("Content-Type", "application/json");
    Request.setHeader("x-market-code", "MKT_GLB");
  • Response Body : JSON forat
    Element Name
    Data Type
    Required
    Description
    developerPayload
    String
    false
  • Example :
    {
    "developerPayload": "your payload"
    }
  • 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
-
  • Example :
    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)

  • 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:
    Parameter Name
    Data Type
    Required
    Description
    Authorization
    String
    true
    Access Token API를 통해 발급받은 access_token
    Content-Type
    String
    true
    application/json
    x-market-code
    String
    false
    마켓 구분 코드
  • Example
    Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4");
    Request.setHeader("Content-Type", "application/json");
    Request.setHeader("x-market-code", "MKT_GLB");
  • Request Body : JSON format
    Element Name
    Data Type
    Required
    Description
    developerPayload
    String
    false
  • Example :
    {
    "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
-
  • Example :
    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)

  • 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:
    Parameter Name
    Data Type
    Required
    Description
    Authorization
    String
    true
    Access Token API를 통해 발급받은 access_token
    Content-Type
    String
    true
    application/json
    x-market-code
    String
    false
    마켓 구분 코드
  • Example
    Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4");
    Request.setHeader("Content-Type", "application/json");
    Request.setHeader("x-market-code", "MKT_GLB");
  • Request Body : 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
-
  • Example :
    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)

  • 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:
    Parameter Name
    Data Type
    Required
    Description
    Authorization
    String
    true
    Access Token API를 통해 발급받은 access_token
    Content-Type
    String
    true
    application/json
    x-market-code
    String
    false
    마켓 구분 코드
  • Example
    Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4");
    Request.setHeader("Content-Type", "application/json");
    Request.setHeader("x-market-code", "MKT_GLB");
  • Request Body : 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
-
  • Example :
    HTTP/1.1 200 OK
    Content-type: application/json;charset=UTF-8
    {
    "result" : {
    "code" : "Success",
    "message" : "Request has been completed successfully."
    }
    }

getVoidedPurchases (Check purchase cancellation details)

  • 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:
    Parameter Name
    Data Type
    Required
    Description
    Authorization
    String
    true
    Access Token API를 통해 발급받은 access_token
    Content-Type
    String
    true
    application/json
    x-market-code
    String
    false
    마켓 구분 코드
  • Example
    Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4");
    Request.setHeader("Content-Type", "application/json");
    Request.setHeader("x-market-code", "MKT_GLB");
  • Request Body : 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
    -
    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 :
    HTTP/1.1 200 OK
    Content-type: application/json;charset=UTF-8
    {
    "continuationKey": "continuationKey",
    "voidedPurchaseList ": [
    {
    "purchaseId": "19062709124410111299",
    "purchaseTime": 1345678900000,