IAP Helper 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).

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: All other IAP Helper requests work like :
  • The app gets in-app items information of the app whose status in Seller Portal is For sale.
  • 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 (app users 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: All other IAP Helper requests work like :
  • The app gets in-app items information of the app whose status in Seller Portal is Registering or Updating.
  • Only items purchased in OPERATION_MODE_TEST mode are considered owned items.
OPERATION_MODE_TEST_FAILURE

 All IAP Helper 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.

You can review the status of your app in Seller Portal Applications page.





Request

public void setOperationMode( OperationMode _mode )

Parameters

Parameter Type Description
_mode OperationMode (Required) The IAP operating mode that controls the processing of IAP Helper 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

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

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


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.
getJsonString() String Full JSON payload

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 OnGetProductDetailsListener 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)
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)
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.

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 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

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)
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)

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
        }
    }
}

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.

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

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
        }
    }
}

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:
  • 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
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 or operation mode.
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_NEED_SA_LOGIN
(-1014)

 Samsung account is not signed in.





Examples of error pop-up windows.