IAP API for Web Apps

Use the Amazon Services JavaScript to add In-App Purchasing to your web application.

API Structure

In-App Purchasing for web apps includes three elements:

  • Amazon Services JavaScript - The class/API that manages the interaction between a web app and Amazon's native APIs.
  • Purchase Handlers - The web app provides methods 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 web apps that choose to employ In-App Purchasing API.

To include the library, add the following <script> tag to your web app:

<script src="https://resources.amazonwebapps.com/v1/latest/Amazon-Web-App-API.min.js">
</script>

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.