Skip to main content
Samsung Developer Program

Initiate and Verify In-App Item Purchases

This section describes how to start the purchase of an in-app item offered by your Android app and selected by the user, have IAP guide the user through purchase and payment transaction, and return information about the results (either successful or failed).

Note: Samsung IAP Client was previously known as Samsung IAP Helper.


Initiate In-App Item Purchases

Use the startPayment() method to initiate a purchase and payment transaction for a specified in-app item.

You can specify your own pass-through parameter and use it for purchase and payment verification. For example, your app server can generate, administer, and provide pass-through parameter values to your Android app, which includes the value in the purchase method call. After the transaction, your app server verifies that the generated value matches the value received in the purchase receipt provided by Samsung IAP.

A boolean parameter controls whether or not a dialog box is displayed after the purchase and payment transaction screens. The dialog box notifies users that the transaction was successful.

After the transaction is complete, a callback is triggered and the onPaymentListener receives information about the purchased item, the transaction, and API call processing.

For more details about IAP Client API elements, see:


To enable a user to purchase an in-app item

Note: The example code shows how to set up a purchase UI button, submit a purchase request for a hard-coded in-app item ID, receive the results of the purchase transaction, and display a results message. 

  1.  In the layout in the activity_main.xml file, add a purchase UI button that calls doPurchase().
    <?xml version="1.0" encoding="utf-8"?> 
        <!-- Purchase Button --> 
            android:onClick="doPurchase" /> 

  2. To initiate an in-app item purchase, add the item ID to a doPurchase() purchase request in the class.
    public class MainActivity extends AppCompatActivity implements OnPaymentListener { 
        // Please change the ITEM_ID for your application. 
        // ======================================================================== 
        private static final String ITEM_ID = "Nuclear"; 
        // ======================================================================== 
        private IapHelper mIapHelper = null; 
        protected void onCreate(Bundle savedInstanceState) { 
            mIapHelper = IapHelper.getInstance(this); 
        public void doPurchase(View _view) { 
            // If specified, the passThroughParam value must be generated you. 
            mIapHelper.startPayment(ITEM_ID, "pLKjLKjLJL87=76df56rf+4f5", true, this); 
        public void onPayment(ErrorVo _errorVO, PurchaseVo _purchaseVO) { 
        // Success or failure of payment is processed here. 

    ITEM_ID hard-codes the item ID . You need to create IapHelper in the onCreate() method, and from doPurchase() callstartPayment() that specifies the in-app item purchase and sends a request to Samsung IAP. The fourth argument ('this') refers to the OnPaymentListener interface for the onPayment() callback method that receives in-app item information, and transaction and processing results. Because the Activity above implements OnPaymentListener, “this” is inserted as an argument. 

    The initialization process has been simplified and is now managed internally within the IAP Client. Only payment results enter the onPayment interface.
  3. Process and display the startPayment() purchase request results in an AlertDialog by implementing the onPayment() callback method in the OnPaymentListener interface.
    public void onPayment(ErrorVo _errorVO, PurchaseVo _purchaseVO) { 
        AlertDialog.Builder alert = new AlertDialog.Builder(this); 
                                new DialogInterface.OnClickListener() { 
            public void onClick(DialogInterface dialog, int which) { 
        if (_errorVO != null) { 
            // If payment was successful. 
            // ================================================================ 
            if (_errorVO.getErrorCode() == IapHelper.IAP_ERROR_NONE) { 
                if (_purchaseVO != null) { 
            // ================================================================ 
            // If payment failed. 
            // ================================================================ 
            else { 
            // ================================================================ 
        else { 
            alert.setMessage("ErrorVo is null");

onPayment()gets startPayment() request results and sets up an alert. Based on the results, one of the following is displayed: PurchaseVo object information about the purchase in-app item and transaction when it succeeds, an ErrorVo object error message when the transaction is reported as failed (for example, the user did not authorize payment), or the message 'ErrorVo is null' when request status results were not received (for example, processing failed unexpectedly).


To test your purchase code: 

  • We recommend you run the test in both Developer Test Mode (Success) and Developer Test Mode (Failed).
  • In your Android app code:
    • Set the IAP operating mode to the appropriate test mode.
    • Confirm that all item IDs match the IDs of registered in-app items. 
  • Your Android app and the in-app items must be registered in Seller Office.
  • Run your code.
    Note: The following steps 1. to 6.a. apply when your code implements item purchase similar to the example code in the section above and the method implemented in the IAP5Sample code. Steps 6.b. to 7.a. apply to most code implementations.


  1. In the main screen, click Purchase One Item.  
  2. In the Confirm Password screen, enter your Samsung account password.
  3. Click Confirm
  4. In the Purchase screen, select a payment method. 
  5. Click Buy
  6. When the payment and purchase transaction is successful:
    1. Verify that the confirmation popup is displayed.
    2. Review the PurchaseVo object received by OnPaymentListener and verify that it contains correct details of the in-app item and the transaction.
    3. Review the errorVo object received by OnPaymentListener and verify that it indicates the status IAP_ERROR_NONE.
  7. When the payment and purchase transaction fails:
    1. Review the errorVo object received by OnPaymentListener and verify that it indicates an error status.


Verify In-App Item Purchases

IAP Client enables in-app item purchase verification that involves only your Android app (client verification).  

During a successful in-app item purchase and payment transaction, Samsung IAP assigns a unique purchaseId. Your Android app receives the purchase ID and additional purchase and in-app item information in the PurchaseVo object of the onPaymentListener interface.

However, in certain scenarios, your Android app may not receive the PurchaseVo object (for example, due to network issues), although the purchase and payment transaction were successful. Your Android app can get the same fundamental purchase information by making a getOwnList() request to get theOwnedProductVo object of the OnGetOwnedListListener interface. 


Your Android app can verify an in-app item purchase by using item data registered in Seller Office (which must be provided by means that are independent of Samsung IAP), information your app used to make the item's startPayment() request, and PurchaseVo or OwnedProductVo object information. 

Client verification can be based on the following and other data:

PurchaseVo and OwnedProductVo



Registered item data

mItemId matches    _itemId  
mPaymentId value is specified    
mItemPrice matches   Item's local price at the time of the purchase


Note: We recommend that your Android app and your app server perform the more secure server verification of item purchases.  For details, see Enhanced Verification of In-App Item Purchases.