< NOTE >

This documents are for ONE store IAP SDK v16(API v4). If you are looking for the latest version of ONE store IAP SDK v17(API v5), please refer to the url below:

URL for the latest documents and downloads of ONE store IAP SDK v17(API v5) : https://dev.onestore.co.kr/devpoc/reference/view/IAP_v17

As for the types of In-App Products, you can publish Consumable/Non-Consumable In-App, Non-Renewable In-App, Trial Version In-App, etc. in ONE store developer center IAP. You are required to select the proper In-App product type, considering the characteristics of the service to be provided by an App in the planning stage.

This In-App product is available after being purchased. It is divided into the two types of Non-consumable and Consumable based on whether the purchased product is permanently maintained or not.

• Non-renewable In-App is available for a specified period of time after being purchased, and this product is categorized based on the period of use as seen below in the table.
• All the non-renewable In-App products cannot be purchased more than once using the same mobile device number (MDN)
• However, if the period of the purchased product expires, the corresponding product can be purchased again

Once an In-App purchase is made in a Trial Version App which is distributed for free, the App is unlocked and converted to a paid version one.

It is not recommended to use this legacy product type.

The IAP SDK provides 7 Java classes(or interfaces).

[Table] com.skplanet.dodo package

Main Functions Are Described as Below :

Description

This function creates and returns a new IapPlugin object to request payment or inquiry. On call, it must send a pluginmode string as a required parameter. If normal values are not passed, a commercial server (release) is set by default in the SDK.

On each call, newly created objects are returned. Server settings vary depending on each object

Syntax

static final IapPlugin getPlugin(Context context, String pluginmMode)

Parameters

context

• In the Android Contect, it is recommended to put Activity Context.

pluginmode

• String: string for commercial/development server configuration

• development : development server (IapPlugin.DEVELOPMENT_MODE)

• release : commercial server (IapPlugin.RELEASE_MODE)

Return The IapPlugin instance is returned on success

Description

This function must be called if you have no longer access to the IapPlugin instance (ex. if the developer App is terminated). Call is recommended because the memory leak could occur if the call is not made.

Syntax

void exit()

When the functions are called, requests are made by sending values to parameters.

Description

This function requests payment. PaymentParams values required on call are created using PaymentParams.Builder

Syntax

String sendPaymentRequest(RequestCallback requestCallback, PaymentParams params)

Parameters

requestCallback

• Callback to receive the result of the payment request

params

• The content of the payment request generated by PaymentParams.Builder

Return Request identifier(RequestId) is returned on normal request.

Description

This function make a request to ‘check purchase history’. It is available to check single, multi and all products.

Syntax

String sendCommandPurchaseHistory(RequestCallback requestCallback, ProcessType type, String appId, String... productIds)

Parameters

requestCallback

• Callback to receive the result of the checking request

type

• Decides if the request is processed either as Background only (without UI exposure) or as Foreground if needed (with UI exposure).
• ProcessType.BACKGROUND_ONLY
• ProcessType.FOREGROUND_IF_NEEDED

appId

• The ID of the product (App) that you want to check

productIds

• The ID of the product (In-App) you want to check
• It is available to enter multiple IDs of In-App products that you want to check
• If you set “null”, you can check all products (In-App products)

Return Request identifier(RequestId) is returned on normal request.

Description

This function makes a request to ‘check the product information for the app.’

Syntax

String sendCommandProductInfo(RequestCallback requestCallback, ProcessType type, String appId)

Parameters

requestCallback

• Callback to receive the result of the checking request

type

• Decides if the request is processed either as Background only (without UI exposure) or as Foreground if needed(with UI exposure).
• ProcessType.BACKGROUND_ONLY
• ProcessType.FOREGROUND_IF_NEEDED

appId

• The ID of the product (App) that you want to check

Return Request identifier(RequestId) is returned on successful request

Description

This function makes a request to ‘check purchase availability’. It is available to check single, multi and all products

Syntax

String sendCommandCheckPurchasability(RequestCallback requestCallback, ProcessType type, String appId, String... productIds)

Parameters

requestCallback

• Callback to receive the result of the checking request

type

• Decides if the request is processed either as Background only (without UI exposure) or as Foreground if needed(with UI exposure).
• ProcessType.BACKGROUND_ONLY
• ProcessType.FOREGROUND_IF_NEEDED

appId

• The ID of the product (App) that you want to check

productIds

• The ID of the product (In-App) you want to check
• It is available to enter multiple IDs of In-App products that you want to check (‘null’ is not available)

Return Request-identifier(RequestId) is returned on successful request.

Description

This function makes a request to ‘change the status of purchased product’. For subscription, the withdrawal is requested. For consumable product, point subtraction is requested.

Syntax

String sendCommandChnageProductProperties(RequestCallback requestCallback, ProcessType type, String appId, String action, String... productIds)

Parameters

requestCallback

• Callback to receive the result of the checking request

type

• Decides if the request is processed either as Background only (without UI exposure) or as Foreground if needed(with UI exposure).
• ProcessType.BACKGROUND_ONLY
• ProcessType.FOREGROUND_IF_NEEDED

appId

• The ID of the product (App) whose status will be changed

action

• cancel_subscription : action to request the cancellation of the subscription (Action.cancel_subscription.action())
• subtract_points : action to request the subtraction of available points (Action.subtract_points.action())
• Null is not available

productIds

• The ID of the product (In-App) whose status you want to change.
• It is available to enter multiple IDs of In-App products whose status that you want to change (null is not available).

Return Request-identifier(RequestId) is returned on successful request.

Description

This function makes a request for ‘e-receipt verification’.

Syntax

void sendVerifyReceiptRequest(String appId, String txId, String signData, ReceiptVerificationTask.RequestCallback callback)

Parameters

txId

• It is TxID which is received as a result of the purchase

appId

• The ID of the product (App) which will be reviewed

signData

• It is the receipt which is received as a result of the purchase

callback

• Callback to receive the result of the verification request

Unlike explicit call (Request Explicit), parameter values, which are required for payment requests, must be delivered in the JSON format. If not for backward compatibility, explicit call is recommended.

Description

This function requests payment, and is provided in the existing version for backward compatibility

Syntax

Bundle sendPaymentRequest(String appId, String pId, String productName, String tId, String bpInfo, RequestCallback requestCallback)

Parameters

appId, pId, productName, tId, bpInfo

• You are allowed to use up to 50 characters in Korean and 100 characters in English for product_name, however, it is recommended to use 50 characters or less for the name.

• You are not allowed to use double quotation for tid and product_name
• You are not allowed to use spacing for tid

requestCallback

• Callback to receive the result of the payment request

Return Information, including request identifier (RequestId), is returned on successful request. (null is returned on failure)

Extra Key in Bundle

• req.id : request identifier
• req.rescode : error code for request
• req.resmsg : result message for request

The IAP server creates and sends the result of the purchase request in the JSON-format response data. The type of response data for purchase processing is as follows:

For the result and error code, refer to IAP Reference Result Code

In-App product name returns the value, which is passed at the time of request (if no value is returned, the name registered in the developer center is used). bp_info is not returned in the JSON response.

[Sample TxID for Each Mobile Operator]

{
	"api_version" : "(api version)", 
	"identifier" : "(request id)", 
	"method" : "purchase", 
	"result" : {
		"code" : "(result code)",
		"message" : "(result message)",
		"txid" : "(id)",
		"receipt" : "(encode receipt using Base64)", 
		"count" : "(count of product)",
		"product" : [ { "(product information)" } ]
		}
}

Description

This function performs multiple inquiries (requests).

• Checks purchase history
• Fetches product information (Get title/description)
• Checks purchase availability
• Requests the change of the status of purchased product

Syntax

Bundle sendCommandRequest(String param, RequestCallback requestCallback)

Parameters

param

• String value in the JSON format containing required parameters

requestCallback

• Callback to receive the result of the payment request

Return Information, including request identifier (RequestId), is returned on normal request. (null is returned on failure)

Extra Key in Bundle

• req.id : request identifier
• req.rescode : error code for request
• req.resmsg : result message for request

Method Type

• action: cancel_subscription / action to request the cancellation of the subscription

• action: subtract_points/ action to request the subtraction of available points

Method for Backward Compatibility

The following methods were used in previous version of the IAP, and are not recommended for use

|Method|Description|Req Parameters| |-----|-----|-----| |auth_item|This makes a request to check purchased single/multi products|appid, product_id| |whole_auth_item |This makes a request to check purchased all products |appid| |monthly_withdraw |This makes a request to withdraw from monthly auto renewable subscription |appid, product_id| |item_use |This makes a request to subtract points from consumable products|appid, product_id|

{
	"method" : "(method name)", 
	"param" : {
		"appid" : "(application id)", 
		"product_id" : ["(product id)"], 
		"action" : "(sub action of method)" 
		}
}

For the result and error code, refer to IAP Reference Result Code .

Notice

• The type of [auto-renewal-month] should not be used based on the available days. Instead, it should be used based on endDate (product termination date) after being confirmed in the App.
• status must return the result code and message only if the method respose is:
  • request_purchase_history
  • change_product_properties
    
    
  • auth_item
  • item_use
  • monthly_withdraw

Default Response Data Format

{
	"api_version" : "(api version)", 
	"identifier" : "(request id)", 
	"method" : "purchase", 
	"result" : { 
		"code" : "(result code)", 
		"message" : "(result message)" 
   }
}

Response Data Format of Query (command) for Checking* In case command for checking is requested, product field is included in the result field of the response data. Field information included in the product field varies depending on each method.

*Query (command) for Checking indidates the method requests defined in '(2)sendCommandRequest' (method types: request_product_info, request_purchase_history, check_purchasability, change_product_properties).

{
	"api_version" : "(api version)", 
	"identifier" : "(request id)", 
	"method" : "purchase", 
	"result" : {
		"code" : "(result code)",
		"message" : "(result message)",
		"count" : "(count of product)",
		"product" : [ { "(product information)" } ] 
	}
} 
 

This function is the same as mentioned above, and decides whether Foreground is allowed or not.

Description

This function performs multiple inquiries (requests).

• Checks purchase history
• Fetches product information (Get title/description)
• Checks purchase availability
• Requests the change of the status of purchased product

Syntax

Bundle sendCommandRequest(String param, RequestCallback requestCallback, ProcessType type)

Parameters

param

• String value in the JSON format containing required parameters

requestCallback

• Callback to receive the result of the payment request

type

• Decides if the request is processed either as Background only (without UI exposure) or as Foreground if needed(with UI exposure).
• ProcessType.BACKGROUND_ONLY
• ProcessType.FOREGROUND_IF_NEEDED

Return Information, including request identifier (RequestId), is returned on successful request. (null is returned on failure)

This is the abstract class to receive response results. Upon request, you are required to implement this class, create objects and send parameters.

private IapPlugin.AbsRequestCallback mAbsRequestCallback = new IapPlugin.AbsRequestCallback() {
        @Override
        protected void onResponse(Response response) {
            // Receive normal responses
        }

        @Override
        public void onError(String reqid, String errcode, String errmsg) {
            // Error occurs
        }
    };

AbsRequestCallback provides methods as follows:

Description

This callback function is called when request processing failed.

For the onError error code and message definition, refer IAP Reference Result Code.

Syntax

void onError(String reqid, String errcode, String errmsg)

Parameters

• reqid: request ID
• errcode: error code
• errmsg: error message

Description

This callback function is called when request processing succeeded.

Syntax

void onResponse(Response response)

IapResultCallback. This class converts the string type results received from the server into the class type.

In the previous versions, the developer directly converted the results through the helper package in the sample project. However a modification is made in this version to pass the converted results to the developer.

All the fields allow direct access as public. All the fields could be null. If information is not received from the server, the default value will be null.

public class Response {
    public final String api_version;
    public final String identifier;
    public final String method;
    public final Result result;
    ...
}

public static class Result {
    public final String message;
    public final String code;
    public final String txid;
    public final String receipt;
    public final Integer count;
    public final List<Product> product;
    ...
}

public static class Product {
    public String appid;
    public String id;
    public String name;
    public String type;
    public String kind;
    public Integer validity;
    public Double price;
    public String startDate;
    public String endDate;
    public Boolean purchasability;
    public Status status;
    ...
}

public static class Status {
    public String code;
    public String message;
    ...
}

This enum defines the type of request processing

public enum ProcessType {
    BACKGROUND_ONLY,
    FOREGROUND_IF_NEEDED,
}

It is recommended to set FOREGROUND_IF_NEEDED by default.

In some cases, UI exposure is requested in the processing of request. For instance,

• Permission request screen
• ONE store service installation request screen

The cases mentioned above exist. If you want stop the request in these cases and receive error, request BACKGROUND_ONLY.

This callback interface is to receive results by calling IapPlugin.

The callback is set by passing RequestCallback instance. RequestCallback instance is implemented by calling the request method. The corresponsing interface method is called according to the success or failure of request processing.

RequestCallback provides methods as below:

Description

This callback function is called when request processing failed.

For the onError error code and message definition, refer to Home

Syntax

void onError(String rid, String errcode, String errmsg)

Parameters

• rid: request ID
• errcode: error code
• errmsg: error message

Description

This callback function is called when request processing succeeded

For the onResponse result code and message definition, refer to IAP Reference Result Code

Syntax

public void onResponse(IapResponse response)

Parameters

response IapResponse The onResponse is the response data as listed below:

This is an interface to the server response data. The methods are listed as below:

Description

This method returns the length of the response data.

Syntax

long getContentLength())

Return

The length of the response data

Description

This method returns the response data as InputStream.

Syntax

InputStream getContent() throws IOException 

Return

Returns InputStream that can read the response data

Description

This method returns the response data as String. The string is converted to the encoding method, which is returned as getContentEncoding (utf-8 is used as the default encoding method).

Syntax

String getContentToString()

Return

Returns the encoded result as String

Description

This method returns the character data encoding type (utf-8 is used as the default encoding method).

Syntax

String getContentEncoding()

Return Returns the encoding type as String.