ONE store IAP API Upgrade Guide

Overview

This document describes the process of upgrading to ONE store API V6(SDK V19) from API V6(SDK V17).

Main features & changes in IAP V6(SDK V19)

Server API

Add purchaseToken

  • purchaseToken is the key value representing the number of purchase cases in SDK V19, and as the purchase standard key, purchaseToken replaces purchaseId, which had been used as the standard key in SDK V17 API.

  • You can confirm purchaseToken in the resulting response after the successful purchase. For Managed product, purchaseToken and purchaseId are mapped 1:1, and for the auto-renewal in-app, they are mapped 1:N.

Add acknowledge API

  • ‘acknowledge API’ has been added to confirm that the developer recognizes the purchase completion after the purchase is normally completed.

  • ONE store automatically cancels the purchase that has not been called by acknowledgePurchase API within 3 days. Therefore, the developer MUST call ‘acknowledge API’ through SDK API or Server API after the purchase is completed.

  • However, the purchase called up by consumePurchase API is judged as being tacitly acknowledged, and therefore it is not cancelled.

  • In SDK V17, you MUST implement additional acknowledge API calls in the situation where ‘consume’ is not requested (such as the first billing for auto-renewal in-app, or the situation in which Managed product is not consumed in order to prevent the re-payment).

Change standard error response specifications

  • The standard error response specifications of SDK V19 have changed to be text-based to improve readability.

Add market identification code

  • The market identification code has been added in preparation for the in-app within ONE store to be released on multi markets.

For the detailed specifications and changes in API, refer to the followings.

ONE store IAP Server API

Server API Details Change History

PNS

Add message specifications of 3.0.0 version

  • The message specifications have been added in preparation for the in-app within ONE store to be released on multi markets.

  • The message version 3.0.0 is also available in SDK V17.

Features have been added to be able to choose the message version (2.0.0/3.0.0) that receives the message per app on Developer Center.

  • Changes in the message version are immediately applied, and then the message will be transmitted through the newly selected message version.

  • If there are no settings, the message will be transmitted with the existing message version (2.0.0) to maintain backward compatibility.

Add the function to send dummy message tests from Developer Center

  • The message was sent only when the purchase was made/cancelled in the Sandbox or the commercial environments, causing inconvenience in building and testing the PNS server. To improve that, the dummy message transmission feature has been added to Developer Center.

For the message version 3.0.0 specifications, refer to the following.

PNS Message Details Change History

Upgrade procedures

Add purchaseToken to the purchase DB managed directly by the developer

In SDK V19, purchaseToken is used as the base key, and therefore purchaseToken must be added, stored, and managed in the data administering the existing purchases.

You can receive purchaseToken as the SDK API getPurchase API response result through SDK API at the time when the purchase is completed.

Apply ONE store new IAP SDK

The new IAP SDK supporting SDK V19 must be applied.

Add ‘acknowledge’ call logic

Unless purchase is acknowledged within 3 days upon the purchase completion, the purchase will be automatically cancelled. However, if the purchase is processed as ‘consumed’, it will not be cancelled because that is considered ‘acknowledged’.

Therefore, as for all the purchases that have not been processed as ‘consumed’ after the purchase completion, ‘acknowledge’ must be requested.

Apply ServerAPI V6

(You can skip this part if you do not use Server API.)

ServerAPI V6 uses the same OAuth policy and environment as the existing version, and therefore you just need to call it in the same way as V5 ServerAPI.

For the changes in the existing V5 ServerAPI, refer to the following.

Server API Details Change History

Apply PNS new message version (3.0)

(You can skip this part if you already use the PNS service and do not want to change the message specifications.)

Build the PNS server to be able to process the PNS 3.0.0. message version specifications.

Set up the PNS notification URL in Developer Center and send 'Test' to ensure if the normal communication is available.

Check and then save to reflect the settings.

The PNS message might be delayed/lost due to problems with network communications, and therefore you must not use the PNS message as criteria for the provision of items.

How to Resolve Expected Issues After Upgrade

How to use ServerAPI of SDK V17 purchase

purchaseToken will not be issued separately for the purchase paid in SDK V17. Therefore, it is recommended to use the existing V5 ServerAPI.

However, if the purchase paid in V17 is successful, it is viewed as automatically ‘acknowledged’.

How to use ServerAPI of SDK V19 purchase

It is suggested to use V6 ServerAPI by using purchaseToken, which has been received when the purchase is successful.

You can use the existing V5 ServerAP with purchaseId to ensure backward compatibility.

However, changes have been made in the process, such as acknowledge API calls, and therefore it is strongly recommended to shift to V6 ServerAPI.

When the in-app is not consumed after the purchase is successfully made in V17, and the consumption of the in-app is requested on V19 terminals (or vice versa);

The consumption is available by using IAP SDK consume API as before.

However, when you request the consumption by using ServerAPI, use V5 ServerAPI SDK for the purchases made in SDK V17 and use V6 ServerAPI for the purchases made in SDK V19.

Last updated