DISTRIBUTION OF TIZEN-BASED WATCH APPS HAS BEEN DISCONTINUED

Web IAP for Galaxy Watch

Samsung In-App Purchase (IAP) for Galaxy Watch is a Galaxy Store service that allows third-party watch applications to sell in-app items.

IAP for Galaxy Watch only works if your Galaxy Watch is paired with your phone.
The IAP Client for watch communicates with the IAP Client for phone which internally manages communication with supporting IAP services and the Samsung ecosystem (such as Samsung Account, Samsung Checkout, and Samsung Rewards). In other words, it acts as an intermediary between watch app and Samsung IAP system of the phone.

You can concentrate on integrating IAP API calls and IAP Server API calls into your watch app.

To integrate IAP for Galaxy Watch :

  • Using Tizen Extension SDK, IAP Web APIs enable you to easily integrate IAP functionality into your watch app, such as configuring IAP, getting item details, offering and selling items, and managing purchased items.
  • Using Galaxy Watch Studio (formerly Galaxy Watch Designer), you can make your own watch face that prompts for payment after a free trial period, without the complexity of coding. For more details, see the Galaxy Watch Studio online tutorial.

​

By integrating IAP features, your watch apps can sell these types of in-app items:

Item type Description
Consumable App users can use items only one time (for example, coins, special powers, or gems).
Non-consumable App users can use items any number of times (for example, e-books or game boards).
Items cannot be repurchased.
Auto-recurring Subscription These items are purchased automatically at specific intervals.
App users can access items (such as magazines, e-zines, or newspapers) any number of times during a free trial or while their paid subscriptions are active.
App users can cancel at any time after purchase during subscription period.
App users can repurchase items after cancellation.

Integrate IAP into your watch app

This section explains how to prepare your app to sell in-app items using Tizen Extension SDK. You can use Galaxy Watch Studio to make a watch face that prompts for payment after a free trial period, without the complexity of coding.

To prepare for integrating IAP features and testing the integration, do the following.

1. Create a project

Create a project in Tizen Studio. The required_version must be at least 2.3.2 in the config.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns:tizen="http://tizen.org/ns/widgets" xmlns="http://www.w3.org/ns/widgets" id="http://yourdomain/webiap" version="1.0.6" viewmodes="maximized">
   <tizen:application id="wxwMXRceLO.webiap" package="wxwMXRceLO" required_version="4.0.0"/>
</widget>

2. Add Permissions to config.xml

<tizen:privilege name="http://tizen.org/privilege/billing"/>

3. Register an app and in-app items in Seller Portal

During IAP integration, you may need to test IAP features. Samsung IAP needs information about your app and in-app items registered in Seller Portal.

To register an app and its in-app items:

  1. Sign in to Seller Portal (https://seller.samsungapps.com) using your Samsung account.

  2. Click Add New Application

  3. Click Galaxy Watch, select the default language, and click Next.

  4. In the Binary tab, upload your app TPK.

  5. In the App Information tab, enter fundamental app details.

  6. In the Country / Region & Price tab, specify a free or paid app, a paid app price, and countries to sell your items.

  7. In the In App Purchase tab, register one or more in-app items

4. Integrate IAP features

Operation mode

IAP supports three operational modes. One is for enabling billing for item purchases and the other two are for testing IAP functions without billing app users for item purchases.

Mode Description
IAP_COMMERCIAL_MODE

 Financial transactions do occur for successful requests, and actual results are returned (successful or failed).
The app gets in-app item information of the app whose status in Seller Portal is For sale.
IAP_SUCCESS_TEST_MODE

 Financial transactions do not occur (app users are not billed for item purchases), and successful results are always returned.
The app gets in-app item information of the app whose status in Seller Portal is Registering or Updating.
IAP_FAILURE_TEST_MODE

 All IAP requests fail.
Negative testing to ensure that your app can handle errors such as improper input and user actions.

Get in-app items available for purchase

To get all registered in-app items from Galaxy Store, use the getItemList() method.

Pass in the index of the first and last item, the item type, service mode, callback function, and user data as parameters.

When the reply is delivered, the GetItemSuccessCallback or ErrorCallback callback is invoked with the JsonObject that stores the query results.

Request

For details, see the getItemList()

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

Response

[Callback=FunctionOnly, NoInterfaceObject] interface GetItemSuccessCallback {
    void onsuccess(JsonObject result);
};
  
[Callback=FunctionOnly, NoInterfaceObject] interface ErrorCallback {
    void onerror (WebAPIError error);
};
  • Common result
Key Value type Description
mErrorCode int Error code number
mErrorString String Error message
_items Array Item list

  • Item details
Key Value type Description
mItemId String Item ID number
This is the same as the item ID used in the request.
mItemName String Name provided during the item registration in the Seller Portal
mItemPrice String Item price in a local currency
mItemPriceString String Currency code + price
For example: €7.99
mCurrencyUnit String Device user currency unit
For example: $, Won, or Pound
mCurrencyCode String Currency code
For example: EUR or GBP
mItemDesc String Item description provided during the item registration
mItemImageUrl String Item image URL provided during the item registration
mItemDownloadUrl String Item download URL provided during the item registration
mType String Item type:
00: Consumable
01: Non-consumable
02: Non-recurring Subscription
03: Auto-recurring Subscription
10: All
mSubscriptionDurationUnit String Subscription duration unit, defined as an upper case string:
MONTH
mSubscriptionDurationMultiplier

 String If the item type (mType) is 02 or 03, this is the item duration.
Combined with mSubscriptionDurationUnit, it expresses the subscription duration, for example, 1MONTH.

Code snippet

  • Request the available items, and retrieve the item details in the reply callback:

    webapis.inapppurchase.getItemList(1, 15, "CONSUMABLE", "IAP_COMMERCIAL_MODE",successCallback, errorCallback);

    /* Success callback */
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].mItemPrice);
      }
   }
}

/* Error callback */
function errorCallback(error)
{
   /* Error handling */
}

Purchase an in-app item

To purchase items from Galaxy Store, use the startPayment() method.

Pass in the index of the item ID, service mode, callback function, and user data as parameters.

When the reply is delivered, the PaymentSuccessCallback or ErrorCallback callback is invoked with the JsonObject that stores the query results.

Request

For details, see the startPayment()

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

Response

[Callback=FunctionOnly, NoInterfaceObject] interface PaymentSuccessCallback {
    void onsuccess(JsonObject item);
};
  
[Callback=FunctionOnly, NoInterfaceObject] interface ErrorCallback {
    void onerror (WebAPIError error);
};
  • Common result
Key Value type Description
mErrorCode int Error code number
mErrorString String Error message
  • Purchased item details
Key Value type Description
mItemId String Item ID number
This is the same as the item ID used in the request.
mItemName String Name provided during the item registration in the Seller Office
mItemPrice Double Item price in a local currency
mItemPriceString String Currency code + price
For example: €7.99
mCurrencyUnit String Device user currency unit
For example: $, Won, or Pound
mCurrencyCode String Currency code
For example: EUR or GBP
mItemDesc String Item description provided during the item registration
mItemImageUrl String Item image URL provided during the item registration
mItemDownloadUrl String Item download URL provided during the item registration
mPaymentId String ID of the payment
mPurchaseId String Purchase ticket ID used to verify the purchase with the Store IAP server
mPurchaseDate String Date of purchase
For example: "2013-11-15 10:31:23"
mVerifyUrl String Server's URL, which can be used in combination with other parameters to verify the purchase with the IAP server

Code snippet

webapis.inapppurchase.startPayment("item_id", "IAP_COMMERCIAL_MODE", successCallback, errorCallback);

/* Success callback */
function successCallback(item)
{
   console.log("Item ID: " + item.mItemId);
   console.log("Item Name: " + item.mItemName);
   console.log("Item Price: " + item.mItemPrice);
}

/* Error callback */
function errorCallback(error)
{
   /* Error handling */
}

Get a list of purchased items

To get all purchased items from Galaxy Stroe, use the getPurchasedItemList() or getPurchasedItemListByIds() method:

  • For getPurchasedItemList(), pass in the index of the first and last item, the item type, the start and end date, the callback function, and user data as parameters.
  • For getPurchasedItemListByIds(), pass in the item IDs separated by comma (,), the callback function, and user data as parameters.

When the reply is delivered, the GetItemSuccessCallback or ErrorCallback callback is invoked with the JsonObject that stores the query results.

Request

For details, see the getPurchasedItemList() and getPurchasedItemListByIds()

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

void getPurchasedItemListByIds(DOMString[] itemIds, 
                               GetItemSuccessCallback successCallback, 
                               optional ErrorCallback? errorCallback)

Response

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

[Callback=FunctionOnly, NoInterfaceObject] interface ErrorCallback {
    void onerror (WebAPIError error);
};
  • Common result
Key Value type Description
mErrorCode int Error code number
mErrorString String Error message
_items Array Item list
  • Purchased item details
Key Value type Description
mItemId String Item ID number
This is the same as the item ID used in the request.
mItemName String Name provided during the item registration in the Seller Portal
mItemPrice String Item price in a local currency
mItemPriceString String Currency code + price
mCurrencyUnit String Device user currency unit
mCurrencyCode String Currency code
mItemDesc String Item description provided during the item registration
mItemImageUrl String Item image URL provided during the item registration
mItemDownloadUrl String Item download URL provided during item registration
mType String Item type:
00: Consumable
01: Non-consumable
02: Non-recurring Subscription
03: Auto-recurring Subscription
10: All
mPaymentId String ID of the payment
mPurchaseId String ID of the purchase
mPurchaseDate String Date of purchase
For example: "2013-11-15 10:31:23"
mSubscriptionEndDate String If the item type (mType) is 02 or 03, this is the due date
mJsonString String Original JSON string

Code snippet

webapis.inapppurchase.getPurchasedItemList(1, 10, new tizen.TZDate(2020, 01, 01), new tizen.TZDate(2022, 12,31), successCallback, errorCallback);

// item IDs can be obtained by seperating the values returned by the getItemList() with comma(,).
webapis.inapppurchase.getPurchasedItemListByIds("item1,item2,item3", successCallback, errorCallback);

/* Success callback */
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].mItemPrice);
      }
   }
}

/* Error callback */
function errorCallback(error)
{
   /* Error handling */
}

Handling errors

During the IAP process, various errors can occur, for example, due to an unstable network, connection error, invalid account, or invalid product.

If an error occurs, your application receives the WebAPIError error type in the ErrorCallback callback. Handle all errors appropriately.

  • Error Code
Error Name Description
PaymentIsCanceledError Payment canceled
NetworkError Network is not available
IOError IOException
TimeoutError Timeout exception
InitializationError Failure during IAP initialization
NeedAppUpgradeError Samsung IAP upgrade is required
AlreadyPurchasedError Error when a non-consumable product is repurchased or a subscription product is repurchased before the product expiration date
WhileRunningError Error when payment is requested without bundle information
ProductDoesNotExistError Error when the requested item list is not available
ConfirmInBoxError The payment result is not received after requesting payment from the server, and the purchased item list is not confirmed
NotExistLocalPriceError The item is not for sale in the country
NotAvailableShopError IAP is not supported in the country
InvalidValuesError Invalid parameter
NotSupportedError The device does not support IAP
SecurityError This functionality is not allowed
UnknownError Any other error case

Verify a purchase

This server API enables your server and client app to verify that a specified in-app item purchase and payment transaction were successfully completed. The API returns a JSON object with a successful status and details about a successful transaction and the item or with a failure status. This API can help to prevent malicious purchases and ensure that purchase and payment transactions were successful when the client app experiences network interruptions after an item purchase and payment transaction.

Request

https://iap.samsungapps.com/iap/appsItemVerifyIAPReceipt.as?protocolVersion=2.0&purchaseID={purchaseID}
  • The purchaseID is assigned by Samsung IAP.
    Your app receives it in the JsonObject of PaymentSuccessCallback() and the variable name is mPurchaseId.

Response

  • Success

    {
    "itemId" : "item01",
    "paymentId":"ZPMTID20131122GBI0015292", 
    "orderId": "S20200106KRA1908790",  
    "itemName":"Test Pack", 
    "itemDesc":"IAP Test Item. Best value!", 
    "purchaseDate":"2020-11-22 04:22:36",
    "paymentAmount":"9.000", 
    "status":"true", 
    "paymentMethod":"Credit Card", 
    "mode":"REAL", 
}

  • Fail

    {
    "status":"false"
}

Submit the app to Galaxy Store

1. Check the operation mode

After IAP integration, you must check the operation mode before submitting the app.
If you submit the app with IAP_SUCCESS_TEST_MODE, the users will get all the items for free.
So, before beta release or normal publication, confirm if the operation mode is IAP_COMMERCIAL_MODE.

2. Submit the app

When you have created an app version that is ready for review testing and normal publication, register the app and its in-app item, and then click Submit.

For more details, see the App Registration Guide.