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.
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
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.
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):
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
public class OwnedList implements OnGetOwnedListListener {
IapHelper.getOwnedList(IapHelper.PRODUCT_TYPE_ALL, this);
@Override
public void onGetOwnedProducts(ErrorVo _errorVO, ArrayList<OwnedProductVo> _ownedList) {
if (_errorVO != null) {
if (_errorVO.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
if (_ownedList != null) {
for (OwnedProductVo item : _ownedList) {
if (item.getIsConsumable()) {
// TODO: Consume the consumable item not yet consumed
}
}
}
} else {
// TODO: Handle the error
}
}
}
}
Kotlin
iapHelper.getOwnedList(IapHelper.PRODUCT_TYPE_ALL)
{ _errorVO: ErrorVo?, _ownedList: ArrayList<OwnedProductVo>? ->
if (_errorVO != null) {
if (_errorVO.errorCode == IapHelper.IAP_ERROR_NONE) {
if (_ownedList != null) {
for (item in _ownedList) {
if (item.isConsumable) {
// TODO: Consume the consumable item not yet consumed
}
}
}
} 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
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
public class ProductsDetails implements OnGetProductsDetailsListener {
IapHelper.getProductsDetails("Nuclear, Claymore, SpeedUp", this);
@Override
public void onGetProducts(ErrorVo _errorVO, ArrayList<ProductVo> _productList) {
if (_errorVO != null) {
if (_errorVO.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
if (_productList != null) {
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 != null) {
if (_errorVO.errorCode == IapHelper.IAP_ERROR_NONE) {
if (_productList != null) {
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).
(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 pathThroughParam 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 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
public class PurchaseItem implements OnPaymentListener {
IapHelper.startPayment("Nuclear", "pLKjLKjLJL87=76df56rf+4f5", this);
@Override
public void onPayment(ErrorVo _errorVO, PurchaseVo _purchaseVO) {
if (_errorVO != null) {
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 != null) {
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.
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().
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
public class ConsumeItems implements OnConsumePurchasedItemsListener {
final String PURCHASEID = "d215d9abcd17b12578a21c0ea7d8821747b64939732a3243b538d8bcae245590";
IapHelper.consumePurchasedItems(PURCHASEID, this);
@Override
public void onConsumePurchasedItems(ErrorVo _errorVO, ArrayList<ConsumeVo> _consumeList) {
if (_errorVO != null) {
if (_errorVO.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
if (_consumeList != null) {
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 != null) {
if (_errorVO.errorCode == IapHelper.IAP_ERROR_NONE) {
if (_consumeList != null) {
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
"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
public class promotionEligibility implements OnGetPromotionEligibilityListener {
iapHelper.getPromotionEligibility("Nuclear, Claymore, SpeedUp", this);
@Override
public void onGetPromotionEligibility(ErrorVo _errorVO, ArrayList<PromotionEligibilityVo> _pricingList) {
if (_errorVO == null) return;
if (_errorVO.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
if (_pricingList != null) {
for (PromotionEligibilityVo pricing : _pricingList) {
// TODO: Get a pricing of the item
}
}
} else {
// TODO: Handle the error
}
}
}
Kotlin
iapHelper.getPromotionEligibility("Nuclear, Claymore, SpeedUp")
{ _errorVO: ErrorVo?, _pricingList: ArrayList<PromotionEligibilityVo>? ->
if (_errorVO == null) return
if (_errorVO.errorCode == IapHelper.IAP_ERROR_NONE) {
if (_pricingList != null) {
for (item in _pricingList) {
// TODO: Get a pricing of the item
}
}
} else {
// TODO: Handle the error
}
}
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.
(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.
(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 pathThroughParam 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 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
public class SubscriptionChange implements OnChangeSubscriptionPlanListener {
iapHelper.changeSubscriptionPlan(
"oldItem",
"newItem",
HelperDefine.ProrationMode.INSTANT_PRORATED_DATE,
"pLKjLKjLJL87=76df56rf+4f5",
this);
@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.
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.
Manage Your Cookies
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.
