en ko zh

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

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 product purchases and the other two are for testing IAP functions without billing app users for product 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).

Request

public void setOperationMode( OperationMode _mode )

Parameters

Code snippet

Java

iapHelper.setOperationMode(HelperDefine.OperationMode.OPERATION_MODE_TEST);

Kotlin

iapHelper.setOperationMode(HelperDefine.OperationMode.OPERATION_MODE_TEST)

Get user-owned products

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

• Items that were purchased with a single charge to the user's payment method. They are either consumable or non-consumable:
  • Consumable items that have not yet been used and not yet reported as consumed
  • Non-consumable items
• Subscriptions currently in a free trial or an active subscription period
  • Includes canceled subscriptions 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 product data and processing results specified by the OnGetOwnedListListener interface.

Request

public boolean getOwnedList
(   
    String                        _productType,
    OnGetOwnedListListener        _onGetOwnedListListener
)

Parameters

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

OwnedProductVo

SubscriptionPriceChangeVo

Code snippet

Java

iapHelper.getOwnedList(HelperDefine.PRODUCT_TYPE_ALL, (errorVo, ownedList) -> {
    if (errorVo.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
        for (OwnedProductVo item : ownedList) {
            if (item.getIsConsumable()) {
                // For consumable item, consume the item not yet consumed
                iapHelper.consumePurchasedItems(item.getPurchaseId(), (errorVo, consumeList) -> {
                    // TODO: Handle the result
                });
            } else {
                // For non-consumable item and subscription, acknowledge the purchase not yet acknowledged
                if (item.getAcknowledgedStatus() == HelperDefine.AcknowledgedStatus.NOT_ACKNOWLEDGED) {
                    iapHelper.acknowledgePurchases(item.getPurchaseId(), (errorVo, acknowledgedList) -> {
                        // TODO: Handle the result
                    });
                }
            }
                
            // Check if the subscription price has changed and user consent is required
            SubscriptionPriceChangeVo subscriptionPriceChangeVo = item.getSubscriptionPriceChange();
            if (subscriptionPriceChangeVo != null &&
                subscriptionPriceChangeVo.getPriceChangeMode() == HelperDefine.PriceChangeMode.PRICE_INCREASE_USER_AGREEMENT_REQUIRED &&
                !subscriptionPriceChangeVo.isConsented()) {
                // TODO: Induce user consent
            }
        }
    } 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) {
                // For consumable item, consume the item not yet consumed
                iapHelper.consumePurchasedItems(item.purchaseId) { errorVo: ErrorVo, consumeList: ArrayList<ConsumeVo> ->
                    // TODO: Handle the result
                }
            } else {
                // For non-consumable item and subscription, acknowledge the purchase not yet acknowledged
                if (item.acknowledgedStatus == HelperDefine.AcknowledgedStatus.NOT_ACKNOWLEDGED) {
                    iapHelper.acknowledgePurchases(item.purchaseId) { errorVo: ErrorVo, acknowledgedList: ArrayList<AcknowledgeVo> ->
                        // TODO: Handle the result
                    }
                }
            }
                
            // Check if the subscription price has changed and user consent is required
            val subscriptionPriceChangeVo = item.subscriptionPriceChange
            if (subscriptionPriceChangeVo != null &&
                subscriptionPriceChangeVo.priceChangeMode == HelperDefine.PriceChangeMode.PRICE_INCREASE_USER_AGREEMENT_REQUIRED &&
                !subscriptionPriceChangeVo.isConsented {
                // TODO: Induce user consent
            }
        }
    } else {
        // TODO: Handle the error
    }
}

Get in-app product details

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

Request

public void getProductsDetails
(   
    String                           _productIds,
    OnGetProductsDetailsListener     _onGetProductsDetailsListener
)  

Parameters

Response

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

Parameters

ProductVo

Code snippet

Java

iapHelper.getProductsDetails("Nuclear, Claymore, SpeedUp", (errorVo, productList) -> {
    if (errorVo.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
        for (ProductVo item : productList) {
            // TODO: Get details of the product
        }
    } 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 product
        }
    } else {
        // TODO: Handle the error
    }
}

Purchase an in-app product

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

Request

public boolean startPayment
(
    String                  _itemId,
    OnPaymentListener       _onPaymentListener
)

Parameters

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

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

PurchaseVo

Code snippet

Java

iapHelper.startPayment("Nuclear", (errorVo, purchaseVo) -> {
    if (errorVo.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
        if (purchaseVo != null) {
            if (purchaseVo.getIsConsumable()) {  
                // Consume the consumable item
                iapHelper.consumePurchasedItems(purchaseVo.getPurchaseId(), (errorVo, arrayList) -> {
                    // TODO: Handle the result
                });
            } else {
                // Acknowledge the non-consumable item or subscription
                iapHelper.acknowledgePurchases(purchaseVo.getPurchaseId(), (errorVo, arrayList) -> {
                    // TODO: Handle the result
                });
            }
        }
    } else {
        // TODO: Handle the error
    }
});

Kotlin

iapHelper.startPayment("Nuclear") { errorVo: ErrorVo, purchaseVo: PurchaseVo? ->
    if (errorVo.errorCode == IapHelper.IAP_ERROR_NONE) {
        if (purchaseVo != null) {
            if (purchaseVo.isConsumable) {          
                // Consume the consumable item
                iapHelper.consumePurchasedItems(purchaseVo.purchaseId) { errorVo: ErrorVo, arrayList: ArrayList<ConsumeVo> ->
                    // TODO: Handle the result
                }
            } else {   
                // Acknowledge the non-consumable item or subscription
                iapHelper.acknowledgePurchases(purchaseVo.purchaseId) { errorVo: ErrorVo, arrayList: ArrayList<AcknowledgeVo> ->
                    // TODO: Handle the result
                }
            }
        }
    } else {
        // TODO: Handle the error
    }
}

Notify Samsung IAP that the purchase was processed

After your app has granted entitlement to the user with a successful transaction, your app needs to notify Samsung IAP that the purchase was successfully processed.

The following sections describe the process for acknowledging different types of purchases.

Consumable items

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

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

Non-consumable items and subscriptions

acknowledgePurchases() acknowledges that the user has been granted entitlement for one or more purchased non-consumable items or subscriptions. Returns non-consumable item/subscription data and processing results specified by the OnAcknowledgePurchasesListener interface.

Request

public boolean acknowledgePurchases
(
  String                             _purchaseIds,
  OnAcknowledgePurchasesListener     _onAcknowledgePurchasesListener
)

Parameters

Return value

• true: The request was sent to server successfully and the result will be sent to OnAcknowledgePurchasesListener interface listener.

• false: The request was not sent to server and was not processed.

Response

void onAcknowledgePurchases(ErrorVo errorVo, ArrayList<AcknowledgeVo> acknowledgedList)

Parameters

ConsumeVo/AcknowledgeVo

Code snippet

Java (ConsumeVo)

final String PURCHASEID = "d215d9abcd17b12578a21c0ea7d8821747b64939732a3243b538d8bcae245590";

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

Kotlin (AcknowledgeVo)

val PURCHASEID: String = "d215d9abcd17b12578a21c0ea7d8821747b64939732a3243b538d8bcae245590"

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

Get promotion eligibility for subscription

getPromotionEligibility() returns the pricing options of a subscription, 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

Response

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

Parameters

PromotionEligibilityVo

Code snippet

Java

iapHelper.getPromotionEligibility("Nuclear, Claymore, SpeedUp", (errorVo, 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.

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,
  OnChangeSubscriptionPlanListener _onChangeSubscriptionPlanListener
)

Parameters

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

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

Code snippet

Java

iapHelper.changeSubscriptionPlan(
    "oldItem",
    "newItem",
    HelperDefine.ProrationMode.INSTANT_PRORATED_DATE,
    (errorVo, purchaseVo) -> {
        if (errorVo.getErrorCode() == IapHelper.IAP_ERROR_NONE) {
            if (purchaseVo != null) {
               	// TODO: Check details about your newly purchased subscription
            }
        } else {
           // TODO: Handle the error
        }
});

Kotlin

iapHelper.changeSubscriptionPlan(
    "oldItem",
    "newItem",
    HelperDefine.ProrationMode.INSTANT_PRORATED_DATE)
	{ errorVo: ErrorVo, purchaseVo: PurchaseVo? ->
        if (errorVo.errorCode == IapHelper.IAP_ERROR_NONE) {
            if (purchaseVo != null) {
                // TODO: Check details about your newly purchased subscription
            }
        } else {
            // TODO: Handle the error
    	}
	}

ErrorVo and Response code

ErrorVo

Response code