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).
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_
|
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 Helper requests:
|
OPERATION_MODE_
|
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 Helper requests:
|
OPERATION_MODE_TEST_
|
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. |
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 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 (this includes canceled subscription items until their active subscription period has ended)
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 itemssubscription : Auto-recurring subscription itemsall : 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 |
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):
|
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 itemfalse : 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) |
getSubscription |
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) |
getPassThrough |
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:
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):
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 consumabletrue : Consumable in-app itemfalse : Not a consumable in-app item (Non-consumable item or auto-recurring subscription)
|
getSubscription |
String | For subscription in-app items only, the time basis unit of each subscription period ("YEAR" , "MONTH" , "WEEK" ).Note: The units must be uppercase. |
getSubscription |
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() .
|
getTiered |
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):
|
getTiered |
String | For two-tiered subscription items only, the time basis unit of each subscription period ("YEAR" , "MONTH" , "WEEK" ).Note: The units must be uppercase. |
getTiered |
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() .
|
getTiered |
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. |
_passThrough |
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) 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):
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 consumabletrue : Consumable in-app itemfalse : 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()
|
getPassThrough |
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. |
getItem |
String | URL of the item’s image and thumbnail |
getItem |
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.
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 |
_onConsumePurchasedItems |
(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 toOnConsumePurchasedItemsListener
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 |
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 code0 : Success1 : Invalid purchaseID2 : Failed order3 : Non-consumable item4 : Already consumed5 : Unauthorized user9 : Unexpected service error
|
getStatusString() | String | Status message0 : "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:
|
IAP_ERROR_ (-1001) |
IAP upgrade is required |
IAP_ERROR_COMMON (-1002) |
Error while running IAP Note: Details of possible errors:
|
IAP_ERROR_ (-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:
|
IAP_ERROR_WHILE_RUNNING (-1004) |
Error when a payment request is made without any information. |
IAP_ERROR_ (-1005) |
Error when the requested item is not available Note: Details of possible errors:
|
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_ (-1007) |
Error when the item group ID does not exist. Note: Details of possible errors:
|
IAP_ERROR_ (-1008) |
Error when network is not available. |
IAP_ERROR_ (-1009) |
IOException |
IAP_ERROR_SOCKET_TIMEOUT (-1010) |
SocketTimeoutException |
IAP_ERROR_CONNECT_TIMEOUT (-1011) |
ConnectTimeoutException |
IAP_ERROR_ (-1012) |
The item is not for sale in the country. Note: Details of possible errors:
|
IAP_ERROR_ (-1013) |
IAP is not serviced in the country. Note: Details of possible errors:
|
IAP_ERROR_INVALID_ACCESS_TOKEN (-1015) |
Access token for Samsung account is not valid. |