IAP v2.0 API for Web Apps

IAP v1.0 Deprecation Notice

In July 2014, Amazon released the In-App Purchasing (IAP) v2.0 API, which includes several important updates. In May 2016, Amazon deprecated IAP v1.0 for new and updated app submissions. While this deprecation does not affect apps that are currently live in the Amazon Appstore, any apps submitted as either a new or updated app after May 2016 need to use IAP v2.0.

To learn more about this deprecation, see the blog post Migrate Your IAP v1.0 Apps to v2.0.

For step-by-step instructions on how to migrate your app, see Migrating from IAP v1.0 to IAP v2.0.

API Structure

In-App Purchasing API for JavaScript is comprised of three elements:

  • Amazon Services JavaScript - The class/API that manages the interaction between the application and Amazon's native APIs.
  • Purchase Handlers - The object your application provides to respond to callbacks from the Amazon Services JavaScript. They are registered as an observer to the Amazon Services In-App Purchasing API.
  • Receipt Verification Service - An HTTP service you can use to validate the customer's purchase receipt.

Integration with In-App Purchasing API consists of registering the Purchase Handlers with the Amazon Services JavaScript, calling the API and responding to the callbacks. Depending on how it is running the callbacks could be triggered by your application's calls or they could be called asynchronously so your application should be able to process both modes of operation. Since the callbacks could happen at any time, you must structure your application to be stateless and not depend on any particular state of execution. For instance, a previous session of your application could have initiated a purchase request that was not delivered because the application shut down. When the application restarts and registers its Purchase Handler, it will have the queued purchase delivered.

The following figure shows the flow of IAP for a web application using the Amazon Services JavaScript:

The following list corresponds to the callouts in the above figure:

  1. Implement a Purchase Handler method.
  2. Register your Purchase Handler with the Amazon Services Library.
  3. App initiates an in-app purchase.
  4. Response notification is handled by your Purchase Handler method.

    The above steps represent the minimum required steps. We recommend the following additional steps for a real-world implementation:

  5. Your app persists the receipt.
  6. Your app sends the receipt to you app server.
  7. Your app server sends the receipt to the Amazon RVS for validation, and receives a response.
  8. Your app server sends the response to your app.
  9. Your app persists the result.

The Amazon Services JavaScript

The Amazon Services JavaScript is an integral part of In-App Purchasing API. Once you initiate a purchase via In-App Purchasing API, the library will present an Amazon-branded user interface to complete the transaction. This flow is used by all apps that choose to employ In-App Purchasing API.

Any code that uses Amazon In-App Purchasing API must be used after the amazonPlatformReady event has been fired from the Amazon HTML5 Framework.

document.addEventListener('amazonPlatformReady', function () {
    if(amzn_wa.IAP) {
        //API usage code goes here
    }
});

If an API call is made when the user is not authenticated with Amazon, the Amazon Services library will authenticate the user with Amazon. To ensure a good user experience and confirm the user is logged into Amazon's services, check for entitlements as soon as your application launches.

The library and Amazon's services present the user interface for all aspects of the purchase workflow. They provide the logic to display the purchasable item, perform the 1-Click purchase itself, and handle any preconditions or error scenarios that arise.

In the event a purchase is unsuccessful, the client will present messaging to the customer; your app should not message the customer. For example, if the customer does not have a valid credit card on file, the library redirects the customer to a page where they can update their payment information. You do not need to provide a confirmation or other interstitial dialog to the customer regarding the purchase flow.