IAP API (Samsung Extension)

The In-App Purchase API provides interfaces and methods providing web applications to use the Samsung payment service to offer items for sale inside your app.

This API provides an interface and methods through features such as:

Since: 2.3.2

Table of Contents

Summary of Interfaces and Methods

Interface Method
InAppPurchaseObject
InAppPurchaseManager void startPayment (DOMString itemId, IAPMode mode, PaymentSuccessCallback successCallback, optional ErrorCallback? errorCallback)
void getItemList (long startNumber, long endNumber, ItemType type, IAPMode mode, GetItemSuccessCallback successCallback, optional ErrorCallback? errorCallback)
void getPurchasedItemList (long startNumber, long endNumber, TZDate startDate, TZDate endDate, GetItemSuccessCallback successCallback, optional ErrorCallback? errorCallback)
void getPurchasedItemListByIds (DOMString[] itemIds, GetItemSuccessCallback successCallback, optional ErrorCallback? errorCallback)
PaymentSuccessCallback void onsuccess (JsonObject item)
GetItemSuccessCallback void onsuccess (JsonObject result)

1. Type Definitions

1.1. JsonObject

JSON Object. 
  typedef object JsonObject;

Since: 2.3.2

1.2. IAPMode

Specifies the type of supported IAP Development Mode. 
  enum IAPMode {"IAP_COMMERCIAL_MODE", "IAP_SUCCESS_TEST_MODE", "IAP_FAILURE_TEST_MODE"};

Since: 2.3.2

The following values are supported in this release:

  • IAP_COMMERCIAL_MODE - Production mode. When releasing your application, the service must be set to production mode. The actual payment process occurs only in production mode.
  • IAP_SUCCESS_TEST_MODE - Test mode and always returns successful results.
  • IAP_FAILURE_TEST_MODE - Test mode and always returns failed results.

Remark : Be sure to set IAP_COMMERCIAL_MODE when uploading an application for distribution so that actual payments from customers can be completed

1.3. ItemType

Specifies the type of supported item type. 
  enum ItemType {"CONSUMABLE", "NON_CONSUMABLE", "SUBSCRIPTION", "AUTO_RECURRING_SUBSCRIPTION", "ALL"};

Since: 2.3.2

The following values are supported in this release:

  • CONSUMABLE - Consumable product. If you purchase a product of this type and use it, it is consumed. These products can be repurchased.
  • NON_CONSUMABLE - Once purchased, you can use a product of this type permanently. These products cannot be repurchased.
  • SUBSCRIPTION - Once a certain period has passed after a product purchase, these products can be repurchased.
  • AUTO_RECURRING_SUBSCRIPTION - Auto-recurring subscriptions let app developers sell in-app items every month with automated and recurring billing.
  • ALL - All includes all types stated above.

Remark : Non-consumable product cannot be tested for repurchase. However, repeated testing is available in test mode, not in the production mode, to repurchase every 10 minutes by initializing the mode.

2. Interfaces

2.1. InAppPurchaseObject

The InAppPurchaseObject interface defines what is instantiated by the WebAPIs object from the Tizen Platform. 
  [NoInterfaceObject] interface InAppPurchaseObject {
    readonly attribute InAppPurchaseManager inapppurchase;
  };
    WebAPIs implements InAppPurchaseObject;

Since: 2.3.2

There will be a webapis.inapppurchase object that allows accessing the functionality of the In-App Purchase API.

2.2. InAppPurchaseManager

The InAppPurchaseManager interface is the top-level interface for the In-App Purchase API that provides access to the module functionalities. 
  [NoInterfaceObject] interface InAppPurchaseManager {

     void startPayment(DOMString itemId,
              IAPMode mode,
              PaymentSuccessCallback successCallback,
              optional ErrorCallback? errorCallback) raises (WebAPIException);

     void getItemList(long startNumber,
              long endNumber,
              ItemType type,
              IAPMode mode,
              GetItemSuccessCallback successCallback,
              optional ErrorCallback? errorCallback) raises (WebAPIException);

     void getPurchasedItemList(long startNumber,
              long endNumber,
              TZDate startDate,
              TZDate endDate,
              GetItemSuccessCallback successCallback,
              optional ErrorCallback? errorCallback) raises (WebAPIException);

     void getPurchasedItemListByIds(DOMString[] itemIds,
              GetItemSuccessCallback successCallback,
              optional ErrorCallback? errorCallback) raises (WebAPIException);
  };

Methods

startPayment
Purchases an item on Samsung Gallaxy Apps. 
void startPayment(DOMString itemId, IAPMode mode, PaymentSuccessCallback successCallback, optional ErrorCallback? errorCallback);

Since: 2.3.2

The ErrorCallback method is launched with these error types:

  • PaymentIsCanceledError - If payment is canceled
  • NetworkError - If network is not available
  • IOError - If IO exception is occurred
  • TimeoutError - If Timeout exception is occurred
  • InitializationError - If initialization is failed
  • NeedAppUpgradeError - If Samsung IAP is required upgrade
  • AlreadyPurchasedError - If non-consumable product is repurchased or subscription product is repurchased before the product expiration date
  • WhileRunningError - If payment is requested without bundle information
  • ProductDoesNotExistError - If requested item list is not available
  • ConfirmInBoxError - If payment result is not received after requesting payment from the server, and the purchased item list is not confirmed
  • NotAvailableShopError - If Samsung IAP is not serviced in the country
  • NotExistLocalPriceError - If item is not for sale in the country
  • InvalidValuesError - If any of the input parameters contain an invalid value
  • NotSupportedError - If the given type is not supported on the device
  • SecurityError - If this functionality is not allowed
  • UnknownError - If in any other error case

Privilege level: public

Privilege: http://tizen.org/privilege/billing

Parameters:

  • itemId: Item Id to purchase
  • mode: Mode of IAP Development
  • successCallback: Callback function that is called when the payment has been completed
  • errorCallback [optional] [nullable]: Callback function that is called when an error has occurred

Exceptions:

  • WebAPIException

    • with error type InitializationError, if initialization is failed.

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type SecurityError, if this functionality is not allowed.

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type UnknownError, if in any other error case.

Code example:

 function successCallback(item) {
     console.log("Item ID : " + item.mItemId);
     console.log("Item Name : " + item.mItemName);
     console.log("Price : " + item.mItemPriceString);
     console.log("Item Image URL : " + item.mItemImageUrl);
 }

 function errorCallback(e) {
     console.log(e.name + " : " + e.message);
 }

 webapis.inapppurchase.startPayment("shotgun", "IAP_COMMERCIAL_MODE", successCallback, errorCallback);
getItemList
Gets the list of a specified subset of the items on Samsung Galaxy Apps offered for sale by caller app. 
void getItemList(long startNumber, long endNumber, ItemType type, IAPMode mode, GetItemSuccessCallback successCallback, optional ErrorCallback? errorCallback);

Since: 2.3.2

The ErrorCallback method is launched with these error types:

  • NetworkError - If network is not available
  • IOError - If IO exception is occurred
  • TimeoutError - If Timeout exception is occurred
  • InitializationError - If initialization is failed
  • NeedAppUpgradeError - If Samsung IAP is required upgrade
  • ProductDoesNotExistError - If requested item list is not available
  • NotAvailableShopError - If Samsung IAP is not serviced in the country
  • InvalidValuesError - If any of the input parameters contain an invalid value
  • NotSupportedError - If the given type is not supported on the device
  • SecurityError - If this functionality is not allowed
  • UnknownError - If in any other error case

Privilege level: public

Privilege: http://tizen.org/privilege/billing

Parameters:

  • startNumber: Index of first item on the list. The start number is 1, not 0
  • endNumber: Index of last item on the list
  • type: Type of Item
  • mode: Mode of IAP Development
  • successCallback: Callback function that is called when item has been retrieved
  • errorCallback [optional] [nullable]: Callback function that is called when an error has occurred

Exceptions:

  • WebAPIException

    • with error type InitializationError, if initialization is failed.

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type SecurityError, if this functionality is not allowed.

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type UnknownError, if in any other error case.

Code example:

 function successCallback(result) {
     for(var i = 0; i < result._items.length; i++) {
         console.log("Item ID : " + result._items[i].mItemId);
         console.log("Item Name : " + result._items[i].mItemName);
         console.log("Item Price : " + result._items[i].mItemPriceString);
         console.log("Item Image URL : " + result._items[i].mItemImageUrl);
     }
 }

 function errorCallback(e) {
     console.log(e.name + " : " + e.message);
 }

 webapis.inapppurchase.getItemList(1, 15, "CONSUMABLE", "IAP_COMMERCIAL_MODE", successCallback, errorCallback);
getPurchasedItemList
Gets the list of the purchased items on Samsung Galaxy Apps. 
void getPurchasedItemList(long startNumber, long endNumber, TZDate startDate, TZDate endDate, GetItemSuccessCallback successCallback, optional ErrorCallback? errorCallback);

Since: 2.3.2

The ErrorCallback method is launched with these error types:

  • NetworkError - If network is not available
  • IOError - If IO exception is occurred
  • TimeoutError - If Timeout exception is occurred
  • InitializationError - If initialization is failed
  • NeedAppUpgradeError - If Samsung IAP is required upgrade
  • ProductDoesNotExistError - If requested item list is not available
  • NotAvailableShopError - If Samsung IAP is not serviced in the country
  • InvalidValuesError - If any of the input parameters contain an invalid value
  • NotSupportedError - If the given type is not supported on the device
  • SecurityError - If this functionality is not allowed
  • UnknownError - If in any other error case

Privilege level: public

Privilege: http://tizen.org/privilege/billing

Parameters:

  • startNumber: Index of first item on the list. The start number is 1, not 0
  • endNumber: Index of last item on the list
  • startDate: Start date of the requested inbox list
  • endDate: End date of the requested inbox list
  • successCallback: Callback function that is called when the purchased item has been retrieved
  • errorCallback [optional] [nullable]: Callback function that is called when an error has occurred

Exceptions:

  • WebAPIException

    • with error type InitializationError, if initialization is failed.

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type SecurityError, if this functionality is not allowed.

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type UnknownError, if in any other error case.

Code example:

 function successCallback(result) {
     for(var i = 0; i < result._items.length; i++) {
         console.log("Item ID : " + result._items[i].mItemId);
         console.log("Item Name : " + result._items[i].mItemName);
         console.log("Item Price : " + result._items[i].mItemPriceString);
         console.log("Item Image URL : " + result._items[i].mItemImageUrl);
     }
 }

 function errorCallback(e) {
     console.log(e.name + " : " + e.message);
 }

 webapis.inapppurchase.getPurchasedItemList(1, 15, new tizen.TZDate(2016, 05, 30), new tizen.TZDate(2016, 06, 01), successCallback, errorCallback);
getPurchasedItemListByIds
Gets the list of the purchased items on Samsung Galaxy Apps by Item ID. 
void getPurchasedItemListByIds(DOMString[] itemIds, GetItemSuccessCallback successCallback, optional ErrorCallback? errorCallback);

Since: 2.3.2

The ErrorCallback method is launched with these error types:

  • NetworkError - If network is not available
  • IOError - If IO exception is occurred
  • TimeoutError - If Timeout exception is occurred
  • InitializationError - If initialization is failed
  • NeedAppUpgradeError - If Samsung IAP is required upgrade
  • ProductDoesNotExistError - If requested item list is not available
  • NotAvailableShopError - If Samsung IAP is not serviced in the country
  • InvalidValuesError - If any of the input parameters contain an invalid value
  • NotSupportedError - If the given type is not supported on the device
  • SecurityError - If this functionality is not allowed
  • UnknownError - If in any other error case

Privilege level: public

Privilege: http://tizen.org/privilege/billing

Parameters:

  • itemIds: Item Ids to get list
  • successCallback: Callback function that is called when the purchased item has been retrieved
  • errorCallback [optional] [nullable]: Callback function that is called when an error has occurred

Exceptions:

  • WebAPIException

    • with error type InitializationError, if initialization is failed.

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type SecurityError, if this functionality is not allowed.

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type UnknownError, if in any other error case.

Code example:

 var itemIds = [];

 function successCallback(result) {
     if (result._items.length == 0) {
         console.log("No item");
     } else {
         for(var i = 0; i < result._items.length; i++) {
             console.log("Item ID : " + result._items[i].mItemId);
             console.log("Item Name : " + result._items[i].mItemName);
             console.log("Item Price : " + result._items[i].mItemPriceString);
             console.log("Item Image URL : " + result._items[i].mItemImageUrl);
         }
     }
 }

 function errorCallback(e) {
     console.log(e.name + " : " + e.message);
 }

 function getItemListSuccess(result)
 {
     if (result._items.length == 0) {
         console.log("No item");
     } else {
         for (var i = 0; i < result._items.length; i++) {
             itemIds[i] = result._items[i].mItemId;
         }
         webapis.inapppurchase.getPurchasedItemListByIds(itemIds, successCallback, errorCallback);
     }
 }

 webapis.inapppurchase.getItemList(1, 15, "ALL", "IAP_COMMERCIAL_MODE", getItemListSuccess, errorCallback);

2.3. PaymentSuccessCallback

The PaymentSuccessCallback interface defines the success callback for startPayment(). 
  [Callback=FunctionOnly, NoInterfaceObject] interface PaymentSuccessCallback {
    void onsuccess(JsonObject item);
  };

Since: 2.3.2

Methods

onsuccess
Called when an In-App Purchase payment is completed. 
void onsuccess(JsonObject item);

Since: 2.3.2

Parameters:

  • item: The result of purchase.

2.4. GetItemSuccessCallback

The GetItemSuccessCallback interface defines the success callback for getItemList(), getPurchasedItemList() and getPurchasedItemListByIds(). 
  [Callback=FunctionOnly, NoInterfaceObject] interface GetItemSuccessCallback {
    void onsuccess(JsonObject result);
  };

Since: 2.3.2

Methods

onsuccess
Called when the item list request is completed. 
void onsuccess(JsonObject result);

Since: 2.3.2

Parameters:

  • result: The result of item list.

3. Full WebIDL

module IAP {

  [NoInterfaceObject] interface InAppPurchaseObject {
    readonly attribute InAppPurchaseManager inapppurchase;
  };
    WebAPIs implements InAppPurchaseObject;

  typedef object JsonObject;

  enum IAPMode {"IAP_COMMERCIAL_MODE", "IAP_SUCCESS_TEST_MODE", "IAP_FAILURE_TEST_MODE"};

  enum ItemType {"CONSUMABLE", "NON_CONSUMABLE", "SUBSCRIPTION", "AUTO_RECURRING_SUBSCRIPTION", "ALL"};

  [NoInterfaceObject] interface InAppPurchaseManager {

     void startPayment(DOMString itemId,
              IAPMode mode,
              PaymentSuccessCallback successCallback,
              optional ErrorCallback? errorCallback) raises (WebAPIException);

     void getItemList(long startNumber,
              long endNumber,
              ItemType type,
              IAPMode mode,
              GetItemSuccessCallback successCallback,
              optional ErrorCallback? errorCallback) raises (WebAPIException);

     void getPurchasedItemList(long startNumber,
              long endNumber,
              TZDate startDate,
              TZDate endDate,
              GetItemSuccessCallback successCallback,
              optional ErrorCallback? errorCallback) raises (WebAPIException);

     void getPurchasedItemListByIds(DOMString[] itemIds,
              GetItemSuccessCallback successCallback,
              optional ErrorCallback? errorCallback) raises (WebAPIException);
  };


  [Callback=FunctionOnly, NoInterfaceObject] interface PaymentSuccessCallback {
    void onsuccess(JsonObject item);
  };

  [Callback=FunctionOnly, NoInterfaceObject] interface GetItemSuccessCallback {
    void onsuccess(JsonObject result);
  };
};