English

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

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 NameData TypeRequiredDescription

    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 <Access-Token>");Request.setHeader("Content-Type", "application/json");<!--When the actual request is made, please enter the access token value except for <, > following Bearer-->

    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 <Access-Token>");Request.setHeader("Content-Type", "application/json");<!--When the actual request is made, please enter the access token value except for <, > following Bearer-->

      Request Body: NA

      Response Body:

      Element NameData TypeData SizeRequiredDescription

      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 NameData TypeRequiredDescription

      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 <Access-Token>");Request.setHeader("Content-Type", "application/json");<!--When the actual request is made, please enter the access token value except for <, > following Bearer-->

      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 NameData TypeRequiredDescription

      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 <Access-Token>");Request.setHeader("Content-Type", "application/json");<!--When the actual request is made, please enter the access token value except for <, > following Bearer-->

      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 NameData TypeRequiredDescription

      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 <Access-Token>");Request.setHeader("Content-Type", "application/json");<!--When the actual request is made, please enter the access token value except for <, > following Bearer-->

      Request Body: NA

      Response Body:

      Element NameData TypeData SizeRequiredDescription

      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 NameData TypeRequiredDescription

      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 <Access-Token>");Request.setHeader("Content-Type", "application/json");<!--When the actual request is made, please enter the access token value except for <, > following Bearer-->

      Request Body: NA

      Response Body:

      Element NameData TypeData SizeRequiredDescription

      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 NameData TypeRequiredDescription

      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 <Access-Token>");Request.setHeader("Content-Type", "application/json");<!--When the actual request is made, please enter the access token value except for <, > following Bearer-->

      Request Body: NA

      Response Body:

      Element NameData TypeData SizeRequiredDescription

      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 NameData TypeDescription

      error

      Object

      The error information

      code

      Integer

      The error code

      message

      String

      The error message

      Error Codes

      ClassificationCodeMessage

      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.

Last updated