IAP SDK Programming

Instantiate Samsung In-App Purchase

Before your app can make IAP requests, it must call getInstance() to create a singleton instance of IapHelper.

Request

public static IapHelper getInstance( Context _context )

Parameters

Parameter	Type	Description
_context	Context	(Required) Android Context

Return Value

IapHelper

Code snippet

Java

private IapHelper iapHelper = IapHelper.getInstance(context);

Kotlin

private val iapHelper: IapHelper = IapHelper.getInstance(context)

Set the IAP 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.

If setOperationMode() is not called, operation mode is set to OPERATION_MODE_PRODUCTION by default (testing is not supported, but beta release and normal publication are supported).

CautionEnsure the operation mode is set to OPERATION_MODE_PRODUCTION before submitting for Beta test or normal publication. In other words, OPERATION_MODE_TEST or OPERATION_MODE_TEST_FAILURE must be set only if the app status in Seller Portal is Registering or Updating.

Mode	Description
`OPERATION_MODE_PRODUCTION`	startPayment() requests are processed as specified, financial transactions do occur for successful requests, and actual results are returned (successful or failed). Note: For all other IAP SDK requests: Only items purchased in `OPERATION_MODE_PRODUCTION` mode are considered owned items.
`OPERATION_MODE_TEST`	startPayment() requests are processed as specified, except financial transactions do not occur (licensed testers are not billed for item purchases), and successful results are always returned. For details of the payment window shown in `OPERATION_MODE_TEST` mode, see below. Note: For all other IAP SDK requests: Only items purchased in `OPERATION_MODE_TEST` mode are considered owned items. In order to purchase in-app items, testers must be registered as a License Tester in the seller's Seller Portal profile. In this mode, licensed testers always get your in-app items for free. All other users see an error message if they try to purchase an in-app item.
`OPERATION_MODE_TEST_FAILURE`	All IAP SDK requests fail. It is meant to be a negative testing to ensure that your app can handle errors such as improper input and user actions.

Mode

Description

OPERATION_MODE_PRODUCTION

startPayment() requests are processed as specified, financial transactions do occur for successful requests, and actual results are returned (successful or failed).

Note: For all other IAP SDK requests:

Only items purchased in OPERATION_MODE_PRODUCTION mode are considered owned items.

OPERATION_MODE_TEST

startPayment() requests are processed as specified, except financial transactions do not occur (licensed testers are not billed for item purchases), and successful results are always returned.
For details of the payment window shown in OPERATION_MODE_TEST mode, see below.

Note: For all other IAP SDK requests:

Only items purchased in OPERATION_MODE_TEST mode are considered owned items.
In order to purchase in-app items, testers must be registered as a License Tester in the seller's Seller Portal profile. In this mode, licensed testers always get your in-app items for free. All other users see an error message if they try to purchase an in-app item.

OPERATION_MODE_TEST_FAILURE

All IAP SDK requests fail.
It is meant to be a negative testing to ensure that your app can handle errors such as improper input and user actions.

NoteIf OPERATION_MODE_TEST is set, the pop-up below is displayed and Sandbox is shown at the top right of the payment window to indicate that the app user will not be billed for item purchases.

Request

public void setOperationMode( OperationMode _mode )

Parameters

Parameter	Type	Description
_mode	OperationMode	(Required) The IAP operating mode that controls the processing of IAP SDK API requests: `OPERATION_MODE_PRODUCTION` `OPERATION_MODE_TEST` `OPERATION_MODE_TEST_FAILURE`

Code snippet

Java

iapHelper.setOperationMode(HelperDefine.OperationMode.OPERATION_MODE_TEST);

Kotlin

iapHelper.setOperationMode(HelperDefine.OperationMode.OPERATION_MODE_TEST)

Get user-owned items

RequirementYou must call getOwnedList() whenever launching the application in order to check for unconsumed items or subscription availability.

getOwnedList() returns a list of in-app items that the app user currently has from previous purchases:

Consumable items that have not yet been used and not yet reported as consumed
Non-consumable items
Subscription items currently in a free trial or an active subscription period
- Includes canceled subscription items until their active subscription period has ended
- If the subscription price is changed, includes information such as new price, renewal date, and user consent

getOwnedList() also returns item data and processing results specified by the OnGetOwnedListListener interface.

NotePurchased consumable items must be reported as consumed by calling consumePurchasedItems() to be purchased again, which can be done before or after the app user uses the item in the app. We recommend reporting all listed consumable items that have not been reported as consumed in one consumePurchasedItems() method call in order to avoid system overload or malfunction.

Request

public boolean getOwnedList
(   
    String                        _productType,
    OnGetOwnedListListener        _onGetOwnedListListener
)

Parameters

Parameter	Type	Description
_productType	String	(Required) Type of in-app items to be returned: `item`: Both consumable and non-consumable items `subscription`: Auto-recurring subscription items `all`: Consumable, non-consumable, and auto-recurring subscription items
_onGetOwnedListListener		(Required) Name of the `OnGetOwnedListListener` interface that specifies the item data and processing results to be returned

Return value

true - The request was sent to server successfully and the result will be sent to OnGetOwnedListListener interface listener.
false - The request was not sent to server and was not processed.

Response

void onGetOwnedProducts(ErrorVo errorVo, ArrayList<OwnedProductVo> ownedList)

Parameters

Parameter	Type	Description
errorVo	ErrorVo	Processed request result
ownedList	ArrayList<OwnedProductVo>	Object that contains in-app items owned by the app user

ErrorVo

Getter	Return Type	Description
getErrorCode()	int	Response code For details, see Response Code
getErrorString()	String	Error message
getErrorDetailsString()	String	Additional information about the result
isShowDialog()	boolean	`true`: The error message dialog is displayed after a failed process. `false`: The error message dialog is not displayed after a failed process.

OwnedProductVo

Getter	Return Type	Description
getItemId()	String	Unique ID of the in-app item
getItemName()	String	Title of the in-app item
getItemPrice()	Double	Current local price in the local currency of the in-app item (for example, 7.99)
getItemPriceString()	String	Local currency symbol and price (in the local currency format): Currency symbol + price (for example, £7.99) Price + currency symbol (for example, 66815₫)
getCurrencyUnit()	String	Symbol of the local currency (for example, €, £, or $)
getCurrencyCode()	String	Currency code (3 characters) of the local currency (for example, EUR, GBP, USD)
getItemDesc()	String	Description of the in-app item
getType()	String	Type of in-app item: `"item"`: Consumable or Non-consumable `"subscription"`: Auto-recurring subscription
getIsConsumable()	boolean	Whether or not the in-app item is consumable `true`: Consumable in-app item `false`: Not a consumable in-app item (non-consumable item or auto-recurring subscription) Caution: If `true`, the consumable item has not been reported as consumed. Before it can be repurchased, it must be reported, by calling consumePurchasedItems()
getPaymentId()	String	Unique identifier assigned by Samsung IAP to the confirmed payment of the in-app item
getPurchaseId()	String	Unique identifier assigned by Samsung IAP to the purchase transaction of the in-app item
getPurchaseDate()	String	Date and time of the item purchase and payment transaction (YYYY‑MM‑DD HH:mm:ss)
getSubscriptionEndDate()	String	For subscription in-app items only, the date and time that the item's current subscription period expires (YYYY‑MM‑DD HH:mm:ss)
getPassThroughParam()	String	Unique identifier that your app assigned to the item purchase and payment transaction If a pass-through parameter was not assigned, empty string ("") is returned.
getSubscriptionPriceChange()	SubscriptionPriceChangeVo	Subscription price change information
getJsonString()	String	Full JSON payload

SubscriptionPriceChangeVo

Getter	Return Type	Description
getAppName()	String	Application name
getItemName()	String	Title of the in-app item
getSubscriptionDurationMultiplier()	String	The numeric multiple of the time basis unit that determines the subscription time period The multiplier is combined with the value returned by `getSubscriptionDurationUnit()`.
getSubscriptionDurationUnit()	String	The time basis unit of each subscription period ("YEAR", "MONTH", "WEEK") Note: These units are always returned in uppercase letters.
getStartDate()	String	Date and time when new prices will affect subscribers (YYYY‑MM‑DD HH:mm:ss)
getOriginalLocalPrice()	Double	Original local price of the in-app item (for example, 7.99)
getOriginalLocalPriceString()	String	Local currency symbol and price (in the local currency format): Currency symbol + price (for example, £7.99) Price + currency symbol (for example, 66815₫)
getNewLocalPrice()	Double	New local price of the in-app item (for example, 9.99)
getNewLocalPriceString()	String	Local currency symbol and price (in the local currency format): Currency symbol + price (for example, £9.99) Price + currency symbol (for example, 70000₫)
isConsented()	boolean	Indicates if the user has consented to a price change (see getPriceChangeMode() below) `true`: The user has consented to the price change. `false`: The user has not consented to the price change. If consent is required, Samsung recommends you include a pop-up, notification, or setting that allows the existing subscriber to renew their subscription (see Price Increase Notifications for an example notification). Your message should also provide the deeplink to the subscription detail page from which users can access the consent page (on a Samsung mobile device): samsungapps://SubscriptionDetail?purchaseId={purchaseId}
getPriceChangeMode()	PriceChangeMode	`PRICE_INCREASE_USER_AGREEMENT_REQUIRED`: Price increases which require an existing subscriber's consent Users must explicitly accept the higher price before the subscription can be renewed. `PRICE_INCREASE_NO_USER_AGREEMENT_REQUIRED`: Price increases without requiring existing subscribers to take any action Unless users opt out, they will be charged the new price when the next regular subscription payment is due. `PRICE_DECREASE`: Price decreases applied to existing subscribers when the next regular subscription payment is due

Code snippet

Java

iapHelper.getOwnedList(HelperDefine.PRODUCT_TYPE_ALL, new OnGetOwnedListListener() {
    @Override
    public void onGetOwnedProducts(@NonNull ErrorVo errorVo, @NonNull ArrayList<OwnedProductVo> ownedList) {
        if (errorVo.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
            for (OwnedProductVo item : ownedList) {
                if (item.getIsConsumable()) {
                    // TODO: Consume the consumable item not yet consumed
                }
                
                // TODO: Check if the subscription price has changed and user consent is required
                SubscriptionPriceChangeVo subscriptionPriceChangeVo = item.getSubscriptionPriceChange();
            }
        } else {
            // TODO: Handle the error
        }
    }
});

Kotlin

iapHelper.getOwnedList(IapHelper.PRODUCT_TYPE_ALL)
{ errorVo: ErrorVo, ownedList: ArrayList<OwnedProductVo> ->
    if (errorVo.errorCode == IapHelper.IAP_ERROR_NONE) {
        for (item in ownedList) {
            if (item.isConsumable) {
                // TODO: Consume the consumable item not yet consumed
            }
            
            // TODO: Check if the subscription price has changed and user consent is required
            val subscriptionPriceChangeVo = item.subscriptionPriceChange
        }
    } else {
        // TODO: Handle the error
    }
}

Get in-app item details

getProductsDetails() returns information for one, more, or all in-app items registered to the app.
Returns item data and processing results specified by the OnGetProductsDetailsListener interface.

Request

public void getProductsDetails
(   
    String                           _productIds,
    OnGetProductsDetailsListener     _onGetProductsDetailsListener
)

Parameters

Parameter	Type	Description
_productIds	String	(Required) One or more in-app item IDs specified by either: Empty string ("") that designates all in-app items or One or more unique in-app item ID values, comma delimited (for example, "coins,blocks,lives") You can get the IDs from Seller Portal (Applications page > Click status of the app > In App Purchase tab > Item ID).
_onGetProductsDetailsListener	(Required) Name of the `OnGetProductsDetailsListener` interface that specifies the item data and processing results to be returned

Parameter

Type

Description

_productIds

String

(Required) One or more in-app item IDs specified by either:

Empty string ("") that designates all in-app items or
One or more unique in-app item ID values, comma delimited (for example, "coins,blocks,lives")

You can get the IDs from Seller Portal (Applications page > Click status of the app > In App Purchase tab > Item ID).

_onGetProductsDetailsListener

(Required) Name of the OnGetProductsDetailsListener interface that specifies the item data and processing results to be returned

Response

void onGetProducts(ErrorVo errorVo, ArrayList<ProductVo> productList)

Parameters

Parameter	Type	Description
errorVo	ErrorVo	Processed request result
productList	ArrayList<ProductVo>	Object that contains details of in-app items

ErrorVo

Getter	Return Type	Description
getErrorCode()	int	Response code For details, see Response Code
getErrorString()	String	Error message
getErrorDetailsString()	String	Additional information about the result
isShowDialog()	boolean	`true`: The error message dialog is displayed after a failed process. `false`: The error message dialog is not displayed after a failed process.

ProductVo

Getter	Return Type	Description
getItemId()	String	Unique ID of the in-app item
getItemName()	String	Title of the in-app item
getItemPrice()	Double	Current local price in the local currency of the in-app item (for example, 7.99) Note: When displayed, this string always includes the two digits to the right of the decimal point (and does not display the currency symbol). For example, if the local price is 8 euros, the value "8.00" is displayed. If you don't want to display the decimal point and the two digits to the right of the decimal point when the price is a whole number, use getItemPriceString() instead.
getItemPriceString()	String	Local currency symbol and price (in the local currency format): Currency symbol + price (for example, £7.99) Price + currency symbol (for example, 66815₫) Note: When displayed, if the price is a whole number, the decimal point and the two digits to the right of the decimal point are not displayed. For example, if the local price is 8 euros, the value "€8" is displayed. If you want to display the two digits to the right of the decimal point (even if the price is a whole number), use getItemPrice() instead.
getCurrencyUnit()	String	Symbol of the local currency (for example, €, £, or $)
getCurrencyCode()	String	Currency code (3 characters) of the local currency (for example, EUR, GBP, USD)
getItemDesc()	String	Description of the in-app item
getType()	String	Type of in-app item: `"item"`: Consumable or Non-consumable `"subscription"`: Auto-recurring subscription
getIsConsumable()	boolean	Whether or not the in-app item is consumable `true`: Consumable in-app item `false`: Not a consumable in-app item (Non-consumable item or auto-recurring subscription)
getSubscriptionDurationUnit()	String	For subscription in-app items only, the time basis unit of each subscription period (`"YEAR"`, `"MONTH"`, `"WEEK"`). Note: The units must be uppercase.
getSubscriptionDurationMultiplier()	String	For subscription items only, the numeric multiple of the time basis unit that determines the item's subscription time period (for example, 1YEAR, 2MONTH, 4WEEK) The multiplier is combined with the value returned by `getSubscriptionDurationUnit()`.
getTieredSubscriptionYN()	String	For subscription items only, whether or not the item has two-tiered pricing `"Y"`: The item has one or more lower-price subscription periods followed by regular-price periods `"N"`: The item only has regular-price subscription periods
getTieredPrice()	String	For two-tiered subscription items only, the lower-tier price in local currency (for example, 7.99)
getTieredPriceString()	String	For two-tiered subscription items only, the local currency symbol and price (in the local currency format): Currency symbol + price (for example, £7.99) Price + currency symbol (for example, 66815₫)
getTieredSubscriptionDurationUnit()	String	For two-tiered subscription items only, the time basis unit of each subscription period (`"YEAR"`, `"MONTH"`, `"WEEK"`). Note: The units must be uppercase.
getTieredSubscriptionDurationMultiplier()	String	For two-tiered subscription items only, the numeric multiple of the time basis unit that determines the item's subscription time period (for example, 1YEAR, 2MONTH, 4WEEK) The multiplier is combined with the value returned by `getTieredSubscriptionDurationUnit()`.
getTieredSubscriptionCount()	String	If the item has both lower and regular tier subscription prices, the number of lower-tier subscription periods.
getShowStartDate()	String	Start date and time that the item will be available for purchase (YYYY-MM-DD HH:mm:ss)
getShowEndDate()	String	End date and time after which the item will not be available for purchase (YYYY-MM-DD HH:mm:ss)
getItemImageUrl()	String	URL of the item's image and thumbnail
getItemDownloadUrl()	String	URL to download the item
getFreeTrialPeriod()	String	Duration of the item's pre-subscription free trial period (in days) : 7 to 999 days
getJsonString()	String	Full JSON payload

Code snippet

Java

iapHelper.getProductsDetails("Nuclear, Claymore, SpeedUp", new OnGetProductsDetailsListener() {
    @Override
    public void onGetProducts(@NonNull ErrorVo errorVo, @NonNull ArrayList<ProductVo> productList) {
        if (errorVo.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
            for (ProductVo item : productList) {
                // TODO: Get details of the item
            }
        } else {
            // TODO: Handle the error
        }
    }
});

Kotlin

iapHelper.getProductsDetails("Nuclear, Claymore, SpeedUp")
{ errorVo: ErrorVo, productList: ArrayList<ProductVo> ->
    if (errorVo.errorCode == IapHelper.IAP_ERROR_NONE) {
        for (item in productList) {
            // TODO: Get details of the item
        }
    } else {
        // TODO: Handle the error
    }
}

Purchase an in-app item

startPayment() initiates the purchase and payment transaction of the specified in-app item and can notify the end user if the purchase succeeded or failed. Returns the item data and transaction results and data specified in the OnPaymentListener interface.

You can specify a passThroughParam parameter value to enhance purchase security. During purchases with passThroughParam values created and passed by an IAP-integrated application are returned in the responses.

CautionWhen the IAP operating mode is OPERATION_MODE_PRODUCTION and the app is being distributed in the Galaxy Store, successful processing results in financial transactions (the app user will be billed for item purchases).

Request

public boolean startPayment
(
    String                  _itemId,
    String                  _passThroughParam,
    OnPaymentListener       _onPaymentListener
)

Parameters

Parameter	Type	Description
_itemId	String	(Required) Unique identifier value of the in-app item to be purchased.
_passThroughParam	String	Optional Unique identifier (maximum: 255 bytes) assigned by your Android app to the purchase and payment transaction. When specified, the value will be returned by `OnPaymentListener` interface. When the iap/v6/receipt is called from the Samsung IAP Server API to verify a purchase, the value will be returned by the passThroughParam field.
_onPaymentListener		(Required) Name of the `OnPaymentListener` interface that specifies the purchase and payment transaction data, item data, and processing results to be returned.

Return value

true: The request was sent to server successfully and the result will be sent to OnPaymentListener interface listener.
false: The request was not sent to server and was not processed.

Response

void onPayment(ErrorVo errorVo, PurchaseVo purchaseVo)

Parameters

Parameter	Type	Description
errorVo	ErrorVo	Processed request result
purchaseVo	PurchaseVo	Object that contains the purchase results

ErrorVo

Getter	Return Type	Description
getErrorCode()	int	Response code (for example, -1003) For details, see Response Code
getErrorString()	String	Error message (for example, Already purchased.)
getErrorDetailsString()	String	Additional information about the result (for example, IS9224/6050/NwCbCAxypi)
isShowDialog()	boolean	`true`: The error message dialog is displayed after a failed process. `false`: The error message dialog is not displayed after a failed process.

PurchaseVo

Getter	Return Type	Description
getItemId()	String	Unique ID of the in-app item
getItemName()	String	Title of the in-app item
getItemPrice()	Double	Current local price in the local currency of the in-app item (for example, 7.99) Note: When displayed, this string always includes the two digits to the right of the decimal point (and does not display the currency symbol). For example, if the local price is 8 euros, the value "8.00" is displayed. If you don't want to display the decimal point and the two digits to the right of the decimal point when the price is a whole number, use getItemPriceString() instead.
getItemPriceString()	String	Local currency symbol and price (in the local currency format): Currency symbol + price (for example, £7.99) Price + currency symbol (for example, 66815₫) Note: When displayed, if the price is a whole number, the decimal point and the two digits to the right of the decimal point are not displayed. For example, if the local price is 8 euros, the value "€8" is displayed. If you want to display the two digits to the right of the decimal point (even if the price is a whole number), use getItemPrice() instead.
getCurrencyUnit()	String	Symbol of the local currency (for example, €, £, or $)
getCurrencyCode()	String	Currency code (3 characters) of the local currency (for example, EUR, GBP, USD)
getItemDesc()	String	Description of the in-app item
getType()	String	Type of in-app item: `"item"`: Consumable or Non-consumable `"subscription"`: Auto-recurring subscription
getIsConsumable()	boolean	Whether or not the in-app item is consumable `true`: Consumable in-app item `false`: Not a consumable in-app item (Non-consumable item or auto-recurring subscription) Note: We recommend that after verifying the purchase of a consumable in-app item be reported as consumed by calling consumePurchasedItems().
getPaymentId()	String	Unique identifier assigned by Samsung IAP to the payment transaction of the in-app item
getPurchaseId()	String	Unique identifier assigned by Samsung IAP to the purchase transaction of the in-app item
getPurchaseDate()	String	Date and time of the item purchase (YYYY-MM-DD HH:mm:ss)
getVerifyUrl()	String	Deprecated since IAP 6.0 See Verify a purchase to get the IAP server URL to verify the purchase using the purchase ID returned by `getPurchaseId()`
getPassThroughParam()	String	Unique identifier that your app assigned to the item purchase and payment transaction If a pass-through parameter was not assigned, an empty string ("") is returned.
getItemImageUrl()	String	URL of the item’s image and thumbnail
getItemDownloadUrl()	String	URL to download the item
getOrderId()	String	Unique identifier of the order
getJsonString()	String	Full JSON payload

Code snippet

Java

iapHelper.startPayment("Nuclear", "pLKjLKjLJL87=76df56rf+4f5", new OnPaymentListener() {
    @Override
    public void onPayment(@NonNull ErrorVo errorVo, @Nullable PurchaseVo purchaseVo) {
		if (errorVo.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
            if (purchaseVo != null) {
                String passThroughParam = _purchaseVo.getPassThroughParam();
                // TODO: If you have set a PassThroughParameter in the request,  
                //       you can verify the PassThroughParameter here.

                if (purchaseVo.getIsConsumable()) {
                    String purchaseId = purchaseVo.getPurchaseId();
                    // TODO: Consume the consumable item by calling `consumePurchasedItems()`
            }
        } else {
            // TODO: Handle the error
        }
    }
});

Kotlin

iapHelper.startPayment("Nuclear", "pLKjLKjLJL87=76df56rf+4f5")
{ errorVo: ErrorVo, purchaseVo: PurchaseVo? ->
    if (errorVo.errorCode == IapHelper.IAP_ERROR_NONE) {
        if (purchaseVo != null) {
            val passThroughParam: String = purchaseVo.passThroughParam
            // TODO: If you have set a PassThroughParameter in the request,  
            //       you can verify the PassThroughParameter here.

            if (purchaseVo.isConsumable) {
                val purchaseId: String = purchaseVo.purchaseId
                // TODO: Consume the consumable item by calling `consumePurchasedItems()`
            }
        }
    } else {
        // TODO: Handle the error
    }
}

NoteWhen you try to purchase an item in your app, you will see the pop-up windows similar to the ones shown below. You must be signed in to your Samsung account.

Acknowledge a purchased consumable item

consumePurchasedItems() reports one or more purchased consumable items as consumed, which makes the items available for another purchase. The app user may or may not have used the items. Returns item data and processing results specified by the OnConsumePurchasedItemsListener interface.

NoteWe recommend reporting purchased consumable items immediately after verifying their purchase and reporting all unreported items in one consumePurchasedItems() method call in order to avoid system overload or malfuction.

Request

public boolean consumePurchasedItems
(
  String                             _purchaseIds,
  OnConsumePurchasedItemsListener    _onConsumePurchasedItemsListener
)

Parameters

Parameter	Type	Description
_purchaseIds	String	(Required) One or more unique identifier values (comma delimited) of the purchase and payment transactions of consumable in-app items that are to be reported as consumed
_onConsumePurchasedItemsListener		(Required) Name of the `OnConsumePurchasedItemsListener` interface that specifies the item data and processing results to be returned

Return value

true: The request was sent to server successfully and the result will be sent to OnConsumePurchasedItemsListener interface listener.
false: The request was not sent to server and was not processed.

Response

void onConsumePurchasedItems(ErrorVo errorVo, ArrayList<ConsumeVo> consumeList)

Parameters

Parameter	Type	Description
errorVo	ErrorVo	Processed request result
consumeList	ArrayList<ConsumeVo>	List of consumed items Note: Even if some items fail to consume due to unexpected errors, they are included in the `_consumeList`, and the result of each item can be checked with ConsumeVo.getStatusCode().

ErrorVo

Getter	Return Type	Description
getErrorCode()	int	Response code For details, see Response Code
getErrorString()	String	Error message
getErrorDetailsString()	String	Additional information about the result
isShowDialog()	boolean	`true`: The error message dialog is displayed after a failed process. `false`: The error message dialog is not displayed after a failed process.

ConsumeVo

Getter	Return Type	Description
getPurchaseId()	String	Unique identifier assigned by Samsung IAP to the purchase transaction of the in-app item
getStatusCode()	int	Status code `0` : Success `1` : Invalid purchaseID `2` : Failed order `3` : Non-consumable item `4` : Already consumed `5` : Unauthorized user `9` : Unexpected service error
getStatusString()	String	Status message `0` : "success" `1` : "Can't find order with this purchaseID." `2` : "Can't consume this purchase because it's not successful order." `3` : "This type of item is not consumable." `4` : "This purchase has been consumed already." `5` : "Can't consume this purchase because the user is not authorized to consume this order." `9` : "service error"
getJsonString()	String	Full JSON payload

Code snippet

Java

final String PURCHASEID = "d215d9abcd17b12578a21c0ea7d8821747b64939732a3243b538d8bcae245590";

iapHelper.consumePurchasedItems(PURCHASEID, new OnConsumePurchasedItemsListener() {
    @Override
    public void onConsumePurchasedItems(@NonNull ErrorVo errorVo, @NonNull ArrayList<ConsumeVo> consumeList) {
        if (errorVo.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
            for (ConsumeVo item : consumeList) {
                // TODO: Get details of the consumption
            }
        } else {
            // TODO: Handle the error
        }
    }
});

Kotlin

val PURCHASEID: String = "d215d9abcd17b12578a21c0ea7d8821747b64939732a3243b538d8bcae245590"

iapHelper.consumePurchasedItems(PURCHASEID)
{ errorVo: ErrorVo, consumeList: ArrayList<ConsumeVo> ->
    if (errorVo.errorCode == IapHelper.IAP_ERROR_NONE) {
        for (item in consumeList) {
            // TODO: Get details of the consumption
        }
    } else {
        // TODO: Handle the error
    }
}

Get promotion eligibility for subscription

getPromotionEligibility() returns the pricing options of a subscription item, such as free trials and introductory prices, applicable to the customer. This allows you to inform each customer about promotions they are eligible for when they are making a purchase. Customers can also check for available promotions before payment, thereby encouraging them to make a purchase.

Request

public void getPromotionEligibility
(
  String _itemIds,
  OnGetPromotionEligibilityListener onGetPromotionEligibilityListener
)

Parameters

Parameter	Type	Description
_itemIds	String	(Required) One or more unique in-app item ID values. Multiple values are comma-delimited. For example, "coins,blocks,lives"
_onGetPromotionEligibilityListener		(Required) Defines the `onGetPromotionEligibility()` callback method that sends a pricing policy

Response

void onGetPromotionEligibility(ErrorVo errorVo, ArrayList<PromotionEligibilityVo> pricingList)

Parameters

Parameter	Type	Description
errorVo	ErrorVo	Processed request result
pricingList	ArrayList<PromotionEligibilityVo>	Pricing policy list (see PromotionEligibilityVo).

ErrorVo

Getter	Return Type	Description
getErrorCode()	int	Response code For details, see Response Code
getErrorString()	String	Error message
getErrorDetailsString()	String	Additional information about the result

PromotionEligibilityVo

Getter	Return Type	Description
getItemId()	String	Identifier of purchased item.
getPricing()	String	Pricing that is applied to users: "FreeTrial" - A set period of time that the user can use the in-app item for free. See Free trial period for more information about this type of subscription. "TieredPrice" - A subscription that charges an introductory price for a limited amount of time. See Lower-Tier or introductory subscription for more information about this type of subscription. "RegularPrice" - A subscription that charges a set price for each subscription period. See Regular or regular-tier subscription for more information about this type of subscription.

Getter

Return Type

Description

getItemId()

String

Identifier of purchased item.

getPricing()

String

Pricing that is applied to users:

"FreeTrial" - A set period of time that the user can use the in-app item for free. See Free trial period for more information about this type of subscription.
"TieredPrice" - A subscription that charges an introductory price for a limited amount of time. See Lower-Tier or introductory subscription for more information about this type of subscription.
"RegularPrice" - A subscription that charges a set price for each subscription period. See Regular or regular-tier subscription for more information about this type of subscription.

Code snippet

Java

iapHelper.getPromotionEligibility("Nuclear, Claymore, SpeedUp", new OnGetPromotionEligibilityListener() {
    @Override
    public void onGetPromotionEligibility(@NonNull ErrorVo errorVo, @NonNull ArrayList<PromotionEligibilityVo> pricingList) {
        if (errorVo.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
            for (PromotionEligibilityVo pricing : pricingList) {
                // TODO: Get the pricing options of the subscription
            }
        } else {
            // TODO: Handle the error
        }
    }
});

Kotlin

iapHelper.getPromotionEligibility("Nuclear, Claymore, SpeedUp")
{ errorVo: ErrorVo, pricingList: ArrayList<PromotionEligibilityVo> ->
    if (errorVo.errorCode == IapHelper.IAP_ERROR_NONE) {
        for (item in pricingList) {
            // TODO: Get the pricing options of the subscription
        }
    } else {
        // TODO: Handle the error
    }
}

Change subscription plan

changeSubscriptionPlan() allows your customer to change their existing subscription to another tier of the same subscription item.

A change may be an upgrade (from a lower priced tier to a higher priced tier or changing between two equally priced tiers) or a downgrade (from a higher priced tier to a lower priced tier).

You must specify a prorationMode to choose how to apply changes to the payment and current subscription period.

Request

public boolean changeSubscriptionPlan
(
  String _oldItemId,
  String _newItemId,
  ProrationMode _prorationMode,
  String _passThroughParam,
  OnChangeSubscriptionPlanListener _onChangeSubscriptionPlanListener
)

Parameters

Parameter	Type	Description
oldItemId	String	(Required) Subscription ID currently subscribed to
newItemId	String	(Required) Subscription ID to subscribe to
prorationMode	ProrationMode	(Required) There are four modes that can be set when a subscription is changed: `INSTANT_PRORATED_DATE`: The subscription is upgraded or downgraded immediately. Any time remaining is adjusted based on the price difference and credited toward the new subscription by pushing forward the next billing date. There is no any additional payment. `INSTANT_PRORATED_CHARGE`: For upgraded subscriptions only. The subscription is upgraded immediately but the billing cycle remains the same. The price difference for the remaining period is then charged to the user. `INSTANT_NO_PRORATION`: For upgraded subscriptions only. The subscription is upgraded immediately and the new price is charged when the subscription renews. The billing cycle remains the same. `DEFERRED`: The subscription is upgraded or downgraded when the subscription renews. When the subscription renews, the new price is charged. A downgrade is always executed with this mode. See Proration Modes for more details about the four modes.
passThroughParam	String	(Optional) Unique identifier assigned by your Android app to the purchase and payment transaction (maximum: 255 bytes) When specified, the value will be returned by `onChangeSubscriptionPlanListener` interface. When the iap/v6/receipt is called from the Samsung IAP Server API to verify a purchase, the value will be returned by the passThroughParam field.
onChangeSubscriptionPlanListener		(Required) Name of the `OnChangeSubscriptionPlanListener` interface that specifies the purchase and payment transaction data, item data, and processing results to be returned.

Return value

true - The request was sent to server successfully and the result will be sent to OnChangeSubscriptionPlanListener interface listener.
false - The request was not sent to server and was not processed.

Response

void onChangeSubscriptionPlan(ErrorVo errorVo, PurchaseVo purchaseVo)

Parameters

Parameter	Type	Description
errorVo	ErrorVo	Processed request result
purchaseVo	PurchaseVo	Object that contains the purchase results

ErrorVo

Getter	Return Type	Description
getErrorCode()	int	Response code (for example, -1003) For details, see Response Code
getErrorString()	String	Error message (for example, Already purchased.)
getErrorDetailsString()	String	Additional information about the result (for example, IS9224/6050/NwCbCAxypi)
isShowDialog()	boolean	`true`: The error message dialog is displayed after a failed process. `false`: The error message dialog is not displayed after a failed process.

PurchaseVo

Getter	Return Type	Description
getItemId()	String	Unique ID of the in-app item
getItemName()	String	Title of the in-app item
getItemPrice()	Double	Current local price in the local currency of the in-app item (for example, 7.99) Note: When displayed, this string always includes the two digits to the right of the decimal point (and does not display the currency symbol). For example, if the local price is 8 euros, the value "8.00" is displayed. If you don't want to display the decimal point and the two digits to the right of the decimal point when the price is a whole number, use getItemPriceString() instead.
getItemPriceString()	String	Local currency symbol and price (in the local currency format): Currency symbol + price (for example, £7.99) Price + currency symbol (for example, 66815₫) Note: When displayed, if the price is a whole number, the decimal point and the two digits to the right of the decimal point are not displayed. For example, if the local price is 8 euros, the value "€8" is displayed. If you want to display the two digits to the right of the decimal point (even if the price is a whole number), use getItemPrice() instead.
getCurrencyUnit()	String	Symbol of the local currency (for example, €, £, or $)
getCurrencyCode()	String	Currency code (3 characters) of the local currency (for example, EUR, GBP, USD)
getItemDesc()	String	Description of the in-app item
getType()	String	Type of in-app item: `"item"`: Consumable or Non-consumable `"subscription"`: Auto-recurring subscription
getIsConsumable()	boolean	Whether or not the in-app item is consumable `true`: Consumable in-app item `false`: Not a consumable in-app item (Non-consumable item or auto-recurring subscription) Note: We recommend that after verifying the purchase of a consumable in-app item be reported as consumed by calling consumePurchasedItems().
getPaymentId()	String	Unique identifier assigned by Samsung IAP to the payment transaction of the in-app item
getPurchaseId()	String	Unique identifier assigned by Samsung IAP to the purchase transaction of the in-app item
getPurchaseDate()	String	Date and time of the item purchase (YYYY‑MM‑DD HH:mm:ss)
getVerifyUrl()	String	Deprecated since IAP 6.0 See Verify a purchase to get the IAP server URL to verify the purchase using the purchase ID returned by `getPurchaseId()`
getPassThroughParam()	String	Unique identifier that your app assigned to the item purchase and payment transaction If a pass-through parameter was not assigned, an empty string ("") is returned.
getItemImageUrl()	String	URL of the item’s image and thumbnail
getItemDownloadUrl()	String	URL to download the item
getOrderId()	String	Unique identifier of the order
getJsonString()	String	Full JSON payload

Code snippet

Java

iapHelper.changeSubscriptionPlan(
    "oldItem",
    "newItem",
    HelperDefine.ProrationMode.INSTANT_PRORATED_DATE,
    "pLKjLKjLJL87=76df56rf+4f5",
    new OnChangeSubscriptionPlanListener() {
        @Override
        public void onChangeSubscriptionPlan(@NonNull ErrorVo errorVo, @Nullable PurchaseVo purchaseVo) {
            if (errorVo.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
                if (purchaseVo != null) {
                	// TODO: Check details about your newly purchased subscription
                    
                    String passThroughParam = purchaseVo.getPassThroughParam();
                    // TODO: If you have set a PassThroughParameter in the request,
                    //       you can verify the PassThroughParameter here.
                }
            } else {
         	   // TODO: Handle the error
            }
        }
});

Kotlin

iapHelper.changeSubscriptionPlan(
    "oldItem",
    "newItem",
    HelperDefine.ProrationMode.INSTANT_PRORATED_DATE,
    "pLKjLKjLJL87=76df56rf+4f5")
	{ errorVo: ErrorVo, purchaseVo: PurchaseVo? ->
        if (errorVo.errorCode == IapHelper.IAP_ERROR_NONE) {
            if (purchaseVo != null) {
                // TODO: Check details about your newly purchased subscription

                val passThroughParam: String = purchaseVo.passThroughParam
                // TODO: If you have set a PassThroughParameter in the request,  
                //       you can verify the PassThroughParameter here.
            }
        } else {
            // TODO: Handle the error
    	}
	}

Response code

Reponse Code (Value)	Description
IAP_ERROR_NONE (0)	Success
IAP_PAYMENT_IS_CANCELED (1)	Payment canceled
IAP_ERROR_INITIALIZATION (-1000)	Failure during IAP initialization Note: Details of possible errors: `10000` : IAP Client app is invalid. `10001` : Samsung Checkout app is invalid. `10011` : Service initialization failed. Try again.
IAP_ERROR_NEED_APP_UPGRADE (-1001)	IAP upgrade is required
IAP_ERROR_COMMON (-1002)	Error while running IAP Note: Details of possible errors: `1005` : When the subscription is changed, the old item does not exist `1006` : When the subscription is changed, the old item is not subscribed `1012` : When the subscription is changed, the specified item is not a subscription type `1014` : Subscription change has already been requested `7002` : Blocked as a suspicious transaction `9000` : `getOwnedList()` fails when OPERATION_MODE_TEST_FAILURE is set `9005` : `consumePurchasedItems()` fails when OPERATION_MODE_TEST_FAILURE is set `9006` : `PassThroughParam` is not Base64-encoded `9007` : `PassThroughParam` exceeded max length `9010` : The item is not consumed yet `9013` : `getProductsDetails()` fails when OPERATION_MODE_TEST_FAILURE is set `9014` : `startPayment()` fails when OPERATION_MODE_TEST_FAILURE is set `9122` : Invalid MCC `9132` : Invalid token or User ID `9200` : Service Error(Invalid MCC, MNC, or CSC) `9226` : PurchaseID is null or invalid in `consumePurchasedItems()` `9440` : Device under honeycomb is not available `9441` : Service is temporarily unavailable `9701` : Certification fail `100001` : Request result does not return normally due to unexpected error `100008` : Disagree Runtime Permission `100010` : `startPayment()` fails when OPERATION_MODE_TEST is set and the user is not a licensed tester
IAP_ERROR_ALREADY_PURCHASED (-1003)	Error when a non-consumable item is re-purchased or a subscription is re-purchased before its expiration date. Note: Details of possible errors: `9224` : A non-consumable item is re-purchased or a subscription is re-purchased before its expiration date
IAP_ERROR_WHILE_RUNNING (-1004)	Error when a payment request is made without any information.
IAP_ERROR_PRODUCT_DOES_NOT_EXIST (-1005)	Error when the requested item is not available Note: Details of possible errors: `9202` : The requested item is not valid in the country or device where the app was distributed. Please check the app distribution condition in Seller Portal. `9207` : The requested itemID does not exist in the current operation mode. Please check ItemID.
IAP_ERROR_CONFIRM_INBOX (-1006)	Error when the app does not receive the purchase result after making a purchase request to the server. In this case, confirmation the item that requested for purchase is needed because the purchase may have been completed successfully.
IAP_ERROR_ITEM_GROUP_DOES_NOT_EXIST (-1007)	Error when the item group ID does not exist. Note: Details of possible errors: `9201` : There is no registered item information. Please check in-App Purchase activation and item registration in Seller Portal
IAP_ERROR_NETWORK_NOT_AVAILABLE (-1008)	Error when network is not available.
IAP_ERROR_IOEXCEPTION_ERROR (-1009)	IOException
IAP_ERROR_SOCKET_TIMEOUT (-1010)	SocketTimeoutException
IAP_ERROR_CONNECT_TIMEOUT (-1011)	ConnectTimeoutException
IAP_ERROR_NOT_EXIST_LOCAL_PRICE (-1012)	The item is not for sale in the country. Note: Details of possible errors: `9134` : Local price doesn't exist (Unsupported MCC)
IAP_ERROR_NOT_AVAILABLE_SHOP (-1013)	IAP is not serviced in the country. Note: Details of possible errors: `9259` : MCC is valid, but Galaxy Store is not supported
IAP_ERROR_INVALID_ACCESS_TOKEN (-1015)	Access token for Samsung account is not valid.

Examples of error pop-up windows.

NoteIn the error code, the first set of digits displayed before the initial slash should correspond to one of the numbers in the description of the response codes above. For example, in the first pop-up window, 9224 appears in the description for the response code IAP_ERROR_ALREADY_PURCHASED. In the second pop-up window, 9014 appears in the description for the response code IAP_ERROR_COMMON.