DISTRIBUTION OF TIZEN-BASED WATCH APPS HAS BEEN DISCONTINUED
Native 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 the watch app and Samsung IAP phone system.
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 Native APIs enables you to easily integrate IAP functionality into your watch app, such as configuring IAPs, 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).
Nonconsumable
App users can use items any number of times (for example, e-books or game boards). Items cannot be repurchased.
NoteDuring IAP integration testing, if your application is set to TEST mode, the purchase record is initialized every 60 minutes to allow repurchase.
Autorecurring 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.
NoteDuring IAP integration testing, if your application is set to TEST mode, the subscription cycle is automatically renewed every 10 minutes, and the subscription is automatically canceled after 12 renewals.
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. See the Galaxy Watch Studio online tutorial for more information.
To prepare for integrating IAP features and testing the integration, perform the following steps:
1. Create a project
Create a project in Tizen Studio.
The application API version must be at least 2.3.2 in the tizen-manifest.xml file:
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_GALAXYAPPS_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_GALAXYAPPS_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_GALAXYAPPS_FAILURE_TEST_MODE
All IAP requests fail. Negative testing to ensure that your app can handle errors such as improper input and user actions.
NoteThe Tizen emulator only supports these two modes:
IAP_GALAXYAPPS_SUCCESS_TEST_MODE
IAP_GALAXYAPPS_FAILURE_TEST_MODE
If you set the mode to IAP_GALAXYAPPS_COMMERCIAL_MODE, it is automatically changed to IAP_GALAXYAPPS_SUCCESS_TEST_MODE.
Get in-app items available for purchase
To get all registered in-app items from Galaxy Store, use the iap_galaxyapps_get_item_list()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 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() method.
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() method.
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.
mJsonString
String
Original JSON string
Code snippet
To handle the request output data, define a structure for it:
Request the available items, and retrieve the item details in the reply callback:
/* 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;
}
To get a list of all items purchased from Galaxy Store, use the iap_galaxyapps_get_purchased_item_list() or iap_galaxyapps_get_purchased_item_list_by_item_ids() method:
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() method.
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() method.
Date of purchase For example: "2020-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
int ret = iap_galaxyapps_get_purchased_item_list(1, 10, "20200101", "20221231", __get_purchased_item_list_cb, NULL);
if (ret != IAP_GALAXYAPPS_ERROR_NONE) {
/* Error handling */
return;
}
// item IDs can be obtained by seperating the values returned by the iap_galaxyapps_get_item_list() with comma(,).
int ret = iap_galaxyapps_get_purchased_item_list_by_item_ids("item1,item2,item3", __get_purchased_item_list_cb, NULL);
if (ret != IAP_GALAXYAPPS_ERROR_NONE) {
/* Error handling */
return;
}
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;
}
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.
Error Code
Error Code
Description
IAP_GALAXYAPPS_ERROR_NONE
Successful
IAP_GALAXYAPPS_ERROR_PAYMENT_IS_CANCELED
Payment canceled
IAP_GALAXYAPPS_ERROR_NETWORK_NOT_AVAILABLE
Network is not available
IAP_GALAXYAPPS_ERROR_IO_ERROR
IOException
IAP_GALAXYAPPS_ERROR_TIMED_OUT
Timeout exception
IAP_GALAXYAPPS_ERROR_INITIALIZATION
Failure during IAP initialization
IAP_GALAXYAPPS_ERROR_NEED_APP_UPGRADE
Samsung IAP upgrade is required
IAP_GALAXYAPPS_ERROR_COMMON
Error while running IAP
IAP_GALAXYAPPS_ERROR_ALREADY_PURCHASED
Error when a non-consumable product is repurchased or a subscription product is repurchased before the product expiration date
IAP_GALAXYAPPS_ERROR_REQUEST_PAYMENT_WITHOUT_INFO
Error when payment is requested without bundle information
IAP_GALAXYAPPS_ERROR_PRODUCT_DOES_NOT_EXIST
Error when the requested item list is not available
IAP_GALAXYAPPS_ERROR_CONFIRM_INBOX
The payment result is not received after requesting payment from the server, and the purchased item list is not confirmed
IAP_GALAXYAPPS_ERROR_NOT_EXIST_LOCAL_PRICE
The item is not for sale in the country
IAP_GALAXYAPPS_ERROR_NOT_AVAILABLE_SHOP
IAP is not supported in the country
IAP_GALAXYAPPS_ERROR_INVALID_PARAMETER
Invalid parameter
IAP_GALAXYAPPS_ERROR_KEY_NOT_FOUND
Specified key is not found
IAP_GALAXYAPPS_ERROR_NOT_SUPPORTED_DEVICE
The device does not support IAP
IAP_GALAXYAPPS_ERROR_OUT_OF_MEMORY
Out of memory
IAP_GALAXYAPPS_ERROR_PERMISSION_DENIED
Permission denied
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.
The purchaseID is assigned by Samsung IAP.
Your app receives it in the iap_galaxyapps_h object as response of iap_galaxyapps_start_payment() and the key is mPurchaseId.
Response
NoteResponse parameters may be added, changed, and deleted.
NoteBesides verifying a purchase, Samsung IAP Server API also obtains service token information and gets detailed information of an autorecurring subscription item purchase.
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_GALAXYAPPS_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_GALAXYAPPS_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.
We use cookies to improve your experience on our website and to show you relevant
advertising. Manage you settings for our cookies below.
Essential Cookies
These cookies are essential as they enable you to move around the website. This
category cannot be disabled.
Company
Domain
Samsung Electronics
.samsungdeveloperconference.com
Analytical/Performance Cookies
These cookies collect information about how you use our website. for example which
pages you visit most often. All information these cookies collect is used to improve
how the website works.
Company
Domain
LinkedIn
.linkedin.com
Meta (formerly Facebook)
.samsungdeveloperconference.com
Google Inc.
.samsungdeveloperconference.com
Functionality Cookies
These cookies allow our website to remember choices you make (such as your user name, language or the region your are in) and
tailor the website to provide enhanced features and content for you.
Company
Domain
LinkedIn
.ads.linkedin.com, .linkedin.com
Advertising Cookies
These cookies gather information about your browser habits. They remember that
you've visited our website and share this information with other organizations such
as advertisers.
Company
Domain
LinkedIn
.linkedin.com
Meta (formerly Facebook)
.samsungdeveloperconference.com
Google Inc.
.samsungdeveloperconference.com
Preferences Submitted
You have successfully updated your cookie preferences.