Implement pending purchases with Amazon IAP

What if I told you that as a developer you can provide parents with the peace of mind to never experience news headlines such as these:

With Appstore SDK’s new pending purchases feature for the In-App Purchasing (IAP) API, you can now provide users with the assurance that unknown purchases won’t occur when children are using your app. Why does it matter? Because offering the best user experience for IAP flows creates several benefits including positive brand reputation, increased ROI, and customer loyalty to start.

So what are pending purchases?

A pending purchase occurs when a user of a child profile in Amazon Kids requests a purchase inside an app or game. After a child requests a purchase, a notification is sent to the parent. The parent can then approve or decline the purchase through the Parent Dashboard. While waiting for approval, the purchase will be in a pending state. If the parent approves the request, your app can deliver the IAP item.

Here’s a screen recording of the pending purchase flow for Amazon Kids:

Integrating pending purchases with the Appstore SDK

Before you can implement pending purchases there are a few things you will need:

• An app or game implementing the Amazon IAP API. If you would like to implement the API for the first time, you can watch my YouTube tutorial here.
• An app or game upgraded to the latest version of the Appstore SDK - v3.0.4 (Appstore SDK contains the IAP API)
• Fire tablet device for testing (optional)

Now that you are all set, lets look at how you can implement PendingPurchases and the good news is this can be done in 3 steps:

Stage 1: Call enablePendingPurchases to support child request

To enable Pending Purchases, your app must call the PurchasingService.enablePendingPurchases()
method at any point before initiating a purchase in the MainActivity of your app.

Kotlin

class MainActivity : AppCompatActivity() {

    private lateinit var binding: ActivityMainBinding

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        binding = ActivityMainBinding.inflate(layoutInflater)
        val view = binding.root
        setContentView(view)

        PurchasingService.registerListener(this, purchasingListener)
        // The call to enablePendingPurchases is required for your app to receive a PENDING RequestStatus
        PurchasingService.enablePendingPurchases();

 ....

        fun requestInAppPurchase() {
        PurchasingService.purchase(....)
        }
    }

Java

public class MainActivity extends Activity {

    @Override
     public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        PurchasingService.registerListener(...);
        // The call to enablePendingPurchases is required for your app to receive a PENDING RequestStatus
        PurchasingService.enablePendingPurchases();
    }

...

    void requestInAppPurchase() {
        PurchasingService.purchase(...)
    }
}

Stage 2: Parent approval & handle RequestStatus of PENDING

When a child initiates a request for a purchase, the resulting PurchaseResponse object has a RequestStatus of PENDING. Therefore, in your app or game ensure you are monitoring the purchase request status. You must either use Real-Time Notifications (RTN) or regularly call getPurchaseUpdates() to be notified of the purchase status and fulfil the purchase.

Kotlin

private var purchasingListener: PurchasingListener = object : PurchasingListener {
        override fun onUserDataResponse(response: UserDataResponse) {
            if (response.getRequestStatus() == PurchaseResponse.RequestStatus.PENDING) {
             // You can break here and do nothing, or show a modal indicating a request is pending.
             // The Appstore also shows a modal to the user indicating the request is pending before
             // returning the response to your app.
            }
        }
        // ...
 }

Java

class MyListener implements PurchasingListener {
      public void onPurchaseResponse(final PurchaseResponse response) {
         if (response.getRequestStatus() == PurchaseResponse.RequestStatus.PENDING) {
             // You can break here and do nothing, or show a modal indicating a request is pending.
             // The Appstore also shows a modal to the user indicating the request is pending before
             // returning the response to your app.
         }
     }
     // ... 
}

Stage 3: Child approval notification and handling

Once a parent has reviewed the request, the purchase is either:

1. approved, the RequestStatus is updated to SUCCESSFUL and your app follows its regular logic for successful transactions. On Fire devices, users get a notification from the system when a purchase is approved.
2. not approved, such as if the parent declines the purchase or lets the purchase request expire, your app doesn't need to take any further action. When not approved, there will be no notification from RTN and no new transaction when a call to getPurchaseUpdates() is made.

Next steps

Once you have implemented Pending Purchases, you can test out your implementation with the Amazon App Tester. Within the tester you will be able to see the status of the purchases and manipulate them to test out the different scenarios of your users journey.

Here’s a screen recording of the Amazon App Tester in action:

Summary

We hope this feature enables new purchase flows to improve the user experience and review stages for parents and children. Try this feature out and let us know what you think!

Related resources:

• Appstore SDK v3.0.4 docs
• Amazon App Tester
• Implementing Amazon In-App Purchasing API (Part 1) YouTube

To stay up to date with Amazon Appstore developer updates on the following platforms:

📣 Follow @AmazonAppDev on Twitter
📺 Subscribe to our Youtube channel
📧 Sign up for the Developer Newsletter