Wearable native

In-App Purchase

Galaxy Watch In-App Purchase (IAP) is a Galaxy Apps service that lets you sell digital content inside your application, which is installed on the Galaxy Watch device. You can offer your customers a variety of items directly within your paid or free application. The IAP feature can be offered as a consumable, non-consumable, or subscription.

You can use the IAP, for example, in the following scenarios:

  • An application that enables additional features
  • Any application that allows the user to remove ads
  • A watchface that offers a free version for some hours
  • An audio-book application that allows the user to purchase and download new books
  • A game that offers new levels to play
  • An RPG game that allows the user to buy virtual items

Figure: Try and buy watchface

Try and buy watchface

Figure: Buying a virtual item

Buying a virtual item

Item Registration in the Samsung Seller Office

The Samsung Seller Office is where the in-app purchase items are registered and managed, in addition to registering and managing applications in Galaxy Apps.

To register items to the Samsung Seller Office:

  1. Join the Samsung Seller Office.
  2. Set yourself up as a commercial seller.

    In order for any application or item to be sold, you must identify yourself according to the e-commerce laws. The Samsung Seller Office provides a simple way to become a paid seller: you just need to verify your identification and information on how to receive your profits.

    Besides your personal information, you must provide bank account information, or PayPal.

  3. Register an application.

    The IAP service helps you sell items through your application. In order for actual sales to proceed, the application must first be registered on the Samsung Seller Office.

  4. Register items.

    Items must be registered in order to use the IAP feature.

    All item information, except for the item type and item ID, can be changed later, so be sure to select the correct type and ID at the beginning.

  5. Add a payment method for the registered items.

    Once items for sale are ready in the Samsung Seller Office, you must add a purchase logic to your application. Galaxy Watch IAP provides a simple and easy way to add the purchase logic with the In App Purchase APIs.

IAP Process Flow

To sell items inside your application, the Galaxy Watch device must be connected with a host device through Galaxy Wearable application. When the connection has been established, your application can access the IAP service using APIs offered by the IAP Library. The IAP service then conveys requests and responses between your application and the Galaxy Apps over the network.

In practice, your application never directly communicates with the Galaxy Apps server. Your application just calls the IAP APIs and handles the result.

Figure: IAP service flow

IAP service flow

When your application calls the IAP APIs, it can be connected to Galaxy Apps on the host device. Galaxy Apps provides a checkout interface for users to enter their payment method, so your application does not need to handle payment transactions directly.

You can control how the item is consumed in your application, and you can query Galaxy Apps to quickly retrieve the list of purchases that were made by the user. This is useful, for example, when you want to restore the user's purchases when they launch your application.

You can use the following IAP service functions with the IAP APIs in your native application:

  1. Getting a list of items available for purchase
  2. Purchasing an item
  3. Getting a list of purchased items

Verifying the Validity of a Purchase

The IAP service allows a third party server to verify the validity of a purchase, to prevent any malicious purchases.

To check the purchase validity, use the verify URL and purchase ID:

  • Verify URL (URL to verify the validity of a purchase) in IAP uses the following fixed value:
    https://iap.samsungapps.com/iap/appsItemVerifyIAPReceipt.as?protocolVersion=2.0
    
  • Purchase ID is returned as a part of the purchase request result:
    purchase ID : d512d9abcd17b12578a21c0ea7d8821747b64939732a3243b538d8bcae245590
    

In third party client applications, the purchase ID is sent to your server. In your server, you can request the validity of the purchase in the URL format shown below using the verify URL and the purchase ID value:

https://iap.samsungapps.com/iap/appsItemVerifyIAPReceipt.as?protocolVersion=2.0&purchaseID=d215d9abcd17b12578a21c0ea7d8821747b64939732a3243b538d8bcae245590

The IAP server sends the result of the verification check in the following JSON format:

  • When the purchase is valid:
    {
        "itemId" : "57515",
        "paymentId":"ZPMTID20131122GBI0015292",
        "itemName":"Test Pack", 
        "itemDesc":"IAP Test Item. Best value!", 
        "purchaseDate":"2013-11-22 04:22:36",
        "paymentAmount":"9.000", 
        "status":"true", 
        "paymentMethod":"CreditCard", 
        "mode":"REAL", 
    }
    
  • When the purchase is invalid:
    {
        "status":"false"
    }
    
Note
Verifying the validity of a purchase is one of the Samsung IAP Developer API which is also providing obtaining service token information and getting detailed information of Auto Recurring Subscription(ARS) item purchase.

In-App Products

The IAP products are digital products that you offer for sale to the users from inside your application. Examples of digital products include in-game currency, application feature upgrades that enhance the user experience, and new content for your application.

The following table lists the product item types supported by IAP.

Table: Supported product item types
Item type Description
Consumable If you purchase a product of this type and use it, it is consumed. These products can be repurchased.

For example: bullets in games are consumable.

Non-consumable Once purchased, you can use a product of this type permanently. These products cannot be repurchased.

For example: books are non-consumable and do not need to be repurchased.

Note
A non-consumable product cannot be tested for repurchase. However, repeated testing is available in the test mode, not in the commercial mode, to repurchase every 10 minutes by initializing the mode.
Non-recurring subscription

(Short-term)

Once a certain period has passed after a product purchase, these products can be repurchased.

For example: monthly magazines and vouchers with expiration dates can be repurchased after a certain period of time.

Auto-recurring subscription These items are purchased automatically at specific intervals.

For example: you can sell in-app items every month with automated and recurring billing.

All This type includes all the 4 types listed above.

IAP Service Modes

Due to the charges that occur when the user purchases items, the IAP payment service is difficult to test. To allow easy testing, IAP offers different modes to test the service under various conditions.

Table: Service modes
Mode Value Description
Commercial mode IAP_GALAXYAPPS_COMMERCIAL_MODE The production mode.

When releasing your application, the service must be set to this mode. The actual payment process occurs only in this mode.

Test mode IAP_GALAXYAPPS_SUCCESS_TEST_MODE This mode always returns "Success" status
IAP_GALAXYAPPS_FAILURE_TEST_MODE This mode always returns "Fail" status

The mode can be set as a parameter when you request for the available item list and purchase an item.

But the Tizen Emulator only supports these two:

IAP_GALAXYAPPS_SUCCESS_TEST_MODE
IAP_GALAXYAPPS_FAILURE_TEST_MODE

Note
It is important to note that, even if the developer sets the mode to IAP_GALAXYAPPS_COMMERCIAL_MODE, it will be automatically changed to IAP_GALAXYAPPS_SUCCESS_TEST_MODE.

Please be aware of this while using emulator during your development.

int ret = iap_galaxyapps_start_payment(item_name, IAP_GALAXYAPPS_SUCCESS_TEST_MODE, callback, NULL);
if (ret != IAP_GALAXYAPPS_ERROR_NONE) {
    /* Error handling */

    return;
}

Prerequisites

To enable your application to use the IAP functionality:

  1. The Galaxy Watch device must be connected with a host device through Galaxy Wearable application.
  2. To purchase items from Galaxy Apps, the application has to request permission by adding the corresponding privilege to the tizen-manifest.xml file:
    <privileges>
        <privilege>http://tizen.org/privilege/billing</privilege>
    </privileges>
    
  3. The application API version must be at least 2.3.2 in the tizen-manifest.xml file:
    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <manifest xmlns="http://tizen.org/ns/packages" api-version="2.3.2" package="org.tizen.nativeiap" version="1.0.6">
    </manifest>
    
  4. To use the functions and data types of the In App Purchase API, include the <iap-galaxyapps.h> header file in your application:
    #include <iap-galaxyapps.h>
    

    To ensure that an In App Purchase function has been executed properly, make sure that the return is equal to IAP_GALAXYAPPS_ERROR_NONE:

    int ret = iap_galaxyapps_foreach_item_info(reply, foreach_item, NULL);
    if (ret != IAP_GALAXYAPPS_ERROR_NONE) {
        /* Error handling */
    
        return;
    }
    

Getting Items Available for Purchase

To get all registered items from Galaxy Apps, use the iap_galaxyapps_get_item_list() function. 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 iap_galaxyapps_reply_cb callback is invoked with the iap_galaxyapps_h object that stores the query results:

  • To get the request result from the iap_galaxyapps_h object, use the iap_galaxyapps_get_value() function.
  • If the request was successful, you can get all the item details from the iap_galaxyapps_h object using the iap_galaxyapps_foreach_item_info() function.

Output data:

  • Common result
    Table: Common results
    Key Value type Description
    mErrorCode int Error code number
    mErrorString String Error message
    mExtraString String Extra result
    mStartNumber int Index of the first item on the list
    mEndNumber int Index of the last item on the list
    mTotalCount int Total number of items based on the first and last item index
  • Item details
    Table: 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 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: Subscription
    • 03: Auto-recurring subscription
    • 10: All
    mSubscriptionDurationUnit String Subscription duration unit, defined as an upper case string:
    • YEAR
    • MONTH
    • WEEK
    • DAY
    mSubscriptionDurationMultiplier String If the item type (mType) is 02, this is the item duration. Combined with mSubscriptionDurationUnit, it expresses the subscription duration, for example, 1MONTH.
    mJsonString String Original JSON string

To request the item list:

  1. To handle the request output data, define a structure for it:
    struct output_data {
        char* mErrorCode;
        char* mErrorString;
        char* mExtraString;
    
        char* mStartNumber;
        char* mEndNumber;
        char* mTotalCount;
    
        char* mItemId;
        char* mItemName;
        char* mItemPrice;
        char* mItemPriceString;
        char* mCurrencyUnit;
        char* mCurrencyCode;
        char* mItemDesc;
        char* mItemImageUrl;
        char* mItemDownloadUrl;
        char* mPaymentId;
        char* mPurchaseId;
        char* mPurchaseDate;
        char* mVerifyUrl;
        char* mType;
        char* mSubscriptionDurationUnit;
        char* mSubscriptionDurationMultiplier;
        char* mSubscriptionEndDate;
        char* mJsonString;
    };
    typedef struct output_data_s;
    
  2. Request the available items, and retrieve the item details in the reply callback:
    static bool
    __foreach_item(iap_galaxyapps_h handle, void *user_data) {
        output_data value = {0,};
    
        /* Get item properties */
        iap_galaxyapps_get_value(handle, "mItemId", &value.mItemId);
        iap_galaxyapps_get_value(handle, "mItemName", &value.mItemName);
        iap_galaxyapps_get_value(handle, "mItemPriceString", &value.mItemPriceString);
        iap_galaxyapps_get_value(handle, "mItemDesc", &value.mItemDesc);
    
        /* Handle properties */
    
        return true;
    }
    
    /* Callback */
    static void
    __get_item_list_cb(iap_galaxyapps_h reply, iap_galaxyapps_error_e result, void *user_data)
    { 
        if (result != IAP_GALAXYAPPS_ERROR_NONE) {
            char *mErrorString = NULL;
            iap_galaxyapps_get_value(reply, "mErrorString", &mErrorString);
            /* Error handling */
    
            return;
        }
        /* Retrieve all items contained in the handle */
        int ret = iap_galaxyapps_foreach_item_info(reply, __foreach_item, NULL);
        if (ret != IAP_GALAXYAPPS_ERROR_NONE) {
            /* Error handling */
    
            return;
        }
    
        return;
    }
    
    /* Request the available item list */
    int ret = iap_galaxyapps_get_item_list(1, 10, "10", IAP_GALAXYAPPS_COMMERCIAL_MODE, __get_item_list_cb, NULL);
    if (ret != IAP_GALAXYAPPS_ERROR_NONE) {
        /* Error handling */
    
        return;
    }
    

Purchasing an Item

To purchase items from Galaxy Apps, use the iap_galaxyapps_start_payment() function. Pass in the index of the item ID, service mode, callback function, and user data as parameters.

When the reply is delivered, the iap_galaxyapps_reply_cb callback is invoked with the iap_galaxyapps_h object that stores the query results.To get both the request result and the purchased item details from the iap_galaxyapps_h object, use the iap_galaxyapps_get_value() function.

Output data:

  • Common result
    Table: Common result
    Key Value type Description
    mErrorCode int Error code number
    mErrorString String Error message
    mExtraString String Extra result
  • Purchased item details
    Table: 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
    mJsonString String Original JSON string

To purchase the item:

/* Callback */
static void
__purchase_cb(iap_galaxyapps_h reply, iap_galaxyapps_error_e result, void *user_data)
{
    output_data value = {0,};

    if (result != IAP_GALAXYAPPS_ERROR_NONE) {
        iap_galaxyapps_get_value(reply, "mErrorString", &value.mErrorString);
        /* Error handling */

        return;
    }

    /* Get properties of the purchased item */
    iap_galaxyapps_get_value(reply, "mItemId", &value.mItemId);
    iap_galaxyapps_get_value(reply, "mItemName", &value.mItemName);
    iap_galaxyapps_get_value(reply, "mItemPriceString", &value.mItemPriceString);
    iap_galaxyapps_get_value(reply, "mItemDesc", &value.mItemDesc);

    /* Handle properties */

    return;
}

/* Purchase an item */
int ret = iap_galaxyapps_start_payment("item_id", IAP_GALAXYAPPS_COMMERCIAL_MODE, __purchase_cb, NULL);
if (ret != IAP_GALAXYAPPS_ERROR_NONE) {
    /* Error handling */

    return;
}

Getting a List of Purchased Items

To get all purchased items from Galaxy Apps, use the iap_galaxyapps_get_purchased_item_list() or iap_galaxyapps_get_purchased_item_list_by_item_ids() function:

  • For iap_galaxyapps_get_purchased_item_list(), 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 iap_galaxyapps_get_purchased_item_list_by_item_ids(), pass in the item IDs separated by comma (,), the callback function, and user data as parameters.

When the reply is delivered, the iap_galaxyapps_reply_cb callback is invoked with the iap_galaxyapps_h object that stores the query results:

  • To get the request result from the iap_galaxyapps_h object, use the iap_galaxyapps_get_value() function.
  • If the request was successful, you can get all the item details from the iap_galaxyapps_h object using the iap_galaxyapps_foreach_item_info() function.

Output data:

  • Common result
    Table: Common result
    Key Value type Description
    mErrorCode int Error code number
    mErrorString String Error message
    mExtraString String Extra result
    mStartNumber int Index of the first item on the list
    mEndNumber int Index of the last item on the list
    mTotalCount int Total number of items based on the first and last item index
  • Purchased item details
    Table: 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 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: 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, this is the due date
    mJsonString String Original JSON string

To request the purchased item list:

static bool
__foreach_purchased_item(iap_galaxyapps_h handle, void *user_data) {
    output_data value = {0,};

    /* Get properties of the item */
    iap_galaxyapps_get_value(handle, "mItemId", &value.mItemId);
    iap_galaxyapps_get_value(handle, "mItemName", &value.mItemName);
    iap_galaxyapps_get_value(handle, "mItemPriceString", &value.mItemPriceString);
    iap_galaxyapps_get_value(handle, "mItemDesc", &value.mItemDesc);

    /* Handle properties */

    return true;
}

/* Callback */
static void
__get_purchased_item_list_cb(iap_galaxyapps_h reply, iap_galaxyapps_error_e result, void *user_data)
{ 
    if (result != IAP_GALAXYAPPS_ERROR_NONE) {
        char *mErrorString = NULL;
        iap_galaxyapps_get_value(reply, "mErrorString", &mErrorString);
        /* Error handling */

        return;
    }

    /* Retrieve all items contained in the handle */
    int ret = iap_galaxyapps_foreach_item_info(reply, __foreach_purchased_item, NULL);
    if (ret != IAP_GALAXYAPPS_ERROR_NONE) {
        /* Error handling */

        return;
    }

    return;
}

...with iap_galaxyapps_get_purchased_item_list()

int ret = iap_galaxyapps_get_purchased_item_list(1, 10, "20160101", "20161231", __get_purchased_item_list_cb, NULL);
if (ret != IAP_GALAXYAPPS_ERROR_NONE) {
    /* Error handling */

    return;
}

...with iap_galaxyapps_get_purchased_item_list_by_item_ids()

char item_ids[256] = {'\0'};
int total_count = 0;

static bool
__foreach_item(iap_galaxyapps_h handle, void *user_data) {
    char *mItemId = NULL;
    static int count = 0;

    /* Get item ID */
    iap_galaxyapps_get_value(handle, "mItemId", &mItemId);
    if (mItemId != NULL) {
        strncat(item_ids, mItemId, strlen(mItemId));
    }
    if (++count < total_count) {
        strncat(item_ids, ",", strlen(","));    // "item1,item2,item3"
    }

    if (count == total_count) {
        int ret = iap_galaxyapps_get_purchased_item_list_by_item_ids(item_ids, __get_purchased_item_list_cb, NULL);
        if (ret != IAP_GALAXYAPPS_ERROR_NONE) {
            /* Error handling */
        }
        count = 0;
    }

    return true;
}

/* Callback */
static void
__get_item_list_cb(iap_galaxyapps_h reply, iap_galaxyapps_error_e result, void *user_data)
{ 
    if (result != IAP_GALAXYAPPS_ERROR_NONE) {
        /* Error handling */

        return;
    }

    /* Get the number of items */
    char *mTotalCount = NULL;
    iap_galaxyapps_get_value(reply, "mTotalCount", &mTotalCount);
    total_count = atoi(mTotalCount);

    /* Retrieve all items contained in the handle */
    int ret = iap_galaxyapps_foreach_item_info(reply, __foreach_item, NULL);
    if (ret != IAP_GALAXYAPPS_ERROR_NONE) {
        /* Error handling */
    }

    return;
}

/* Request the available item list */
int ret = iap_galaxyapps_get_item_list(1, 5, "00", IAP_GALAXYAPPS_COMMERCIAL_MODE, __get_item_list_cb, NULL);
if (ret != IAP_GALAXYAPPS_ERROR_NONE) {
    /* Error handling */

    return;
}

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 iap_galaxyapps_error_e error type in the iap_galaxyapps_reply_cb callback. Handle all errors appropriately.

Figure: Error handling examples

Try again Already purchased Package includes item already

Go to top