Prerequisite knowledge
 
Before proceeding with this article, read the Adobe Developer Center article: Direct Entitlement Starter Kit, which introduces a kit for getting started with Adobe Digital Publishing Suite Direct Entitlement.
 
Basic knowledge of the following languages: PHP, HTML, JavaScript, MySQL.
 
User level: All
 
Required products
 
Additional requirements
 
Sample files
 
amazon-web-services-simplepay.zip
By downloading software from the Adobe Web site you agree to the terms of our license agreement. Please read it before downloading.
 
 
 
This article describes how to use Amazon's Web Services for the selling and periodic collection of payments associated with a digital-only or premium Adobe Digital Publishing Suite (DPS) folio content. It requires no interaction with a device manufacture's application storefront. This solution works with any application on any type of device (such as iOS, Kindle Fire, and Android) that has been enabled for direct entitlement. Typically, a user on a website initiates Digital subscription purchases, which are outside of the DPS application. Once purchased outside of the application, the subscription is available through direct entitlement inside the application or within the Adobe web viewer (otherwise known as a social sharing viewer).
 
In this article you will learn how to integrate Amazon Simple Pay Subscriptions with Digital Publishing Suite through a Direct Entitlement implementation.
 

 
Understanding the user experience

This section explains the user experience that you will build in this example application. Figure 1 shows the first page in the subscription interface.
 
Figure 1: Subscriptions options web interface
Figure 1: Subscriptions options web interface
 
  1. A user purchases a subscription (see Figure 1).
  2. Control transfers to Amazon where the Amazon website asks the user to sign in and confirm the purchase. (Note the co-branding in upper left corner of the menu as shown in Figure 2).
Figure 2: Amazon Payment Authorization page
Figure 2: Amazon Payment Authorization page
 
  1. The Amazon Payment Authorization page directs the user to your website and displays your desired message.
Figure 3: Subscription confirmation page
Figure 3: Subscription confirmation page
  1. In this example, the previous step auto-generates an e-mail to the user using the e-mail associated with the Amazon consumer account.
  2. The consumer receives the e-mail. The e-mail instructs the user to create an account on the entitlement system.
Note: Gmail or other e-mail clients may treat this notification e-mail as spam if your server is not a valid sender of the e-mail.
 
  1. At this point, the user is entitled to the most recent retail folio within the fulfillment account; the user continues to have entitlement to newly published retail folios.
  2. An optional, but recommended step is as follows: After confirmation, redirect the user to the application on the iPad using the URLScheme defined for the application.

 
Getting started

The solution uses Amazon Simple Pay Subscriptions. According to Amazon, this service offers an "easy-to-use and secure way for those who offer digital content subscriptions, collect membership dues on a periodic basis, or provide premium services on their websites to enable subscriptions or recurring payments."
 
Users with existing Amazon IDs can purchase subscriptions with a single click after authentication. The publisher receives information and status updates as subscribers begin, complete, renew, cancel, or otherwise modify their subscriptions.
 
Before you get started with this tutorial, set up a new e-mail account (for instance, on mail.google.com) that you can use for the business side of the transactions, in other words, "the seller." Doing this separates this web application from any other transactions you may perform on the Amazon website. You will also need a separate/new e-mail account to create a sandbox user that can consume this service, in other words, "the buyer."
 
There are three components for implementing this solution:
 
  1. Configure Amazon Simple Pay Subscriptions: You must set up the business account at Amazon to receive and process payments.
  2. Create a purchase page: Create a web page to access the business account and make a subscription purchase.
  3. Create a website that handles the transactions: Create a website that receives notifications from Amazon and the business account that handles the transactions.
The following steps guide you through setting up a developer/sandbox application on Amazon.
 
 
Configure Amazon Simple Pay Subscriptions
  1. Sign up for an Amazon Flexible Payments Service (FPS) Sandbox account using your "buyer" e-mail account. Use this account to collect and manage payment/subscriptions.
  2. Create an Amazon Payments Business Account on Sandbox. Again, use your "buyer" e-mail account as you did in the previous step.
  3. You're done. You will see the following page display (see Figure 4).
Figure 4: Amazon Payments Sandbox account created
Figure 4: Amazon Payments Sandbox account created
 
 
Create a purchase page
There are a number of ways to create a purchase page using C#, Ruby, Perl or PHP. Amazon's Sample Code and Libraries are an excellent place to start. For our example, we are going to use the stand-alone Library in PHP for Simple Pay Subscriptions. After you download the library, I recommend that you review the README.html file within the ButtonGeneratorWithSignature directory.
 
I've chosen to place the 'src' PHP files (SignatureUtils.php, ButtonGenerator.php) within my 'aws_utils' directory for convenient access.
 
You must provide your own values of $accessKey (Access Key ID) and $secretKey (Secret Access Key), which you can find at: https://portal.aws.amazon.com/gp/aws/securityCredentials, which should contain information similar to Figure 5.
 
Figure 5: Amazon Payments access keys
Figure 5: Amazon Payments access keys
 
Now that you have your access key and secret keys, you can modify the index.php file contained within the example ZIP you downloaded from the Requirements section in the beginning of this article. The only remaining basic item is to set the value of $baseUrl in the settings.php file to the hostname and context root of your application.
 
 
Create your website for handling transactions
  1. Unzip and deploy the amazon-web-services-simplepay.zip, which contains the sample files you downloaded in the Requirements section. Download these files to a publicly addressable web server instance.
  2. Modify $ baseurl in the settings.php file to map to where you deployed the application, for instance, http://lighthouse.adobe.com/dps/simplepay.
  3. Modify $ fulfillment_account in the settings.php file to point to your Adobe Fulfillment account. See the "Connecting to fulfillment" section of the article, Build a Custom Storefront for details.
  4. Create a MySQL database and table using the script in the createDB.sql file. This file creates a simplepay database and a users table.
 
Other configurations and options
  1. Within the subscriptions.php file, the function getSubscriptions() returns an array of objects that contain application-specific subscriptions that are already defined. You might define your own. You can use data from these subscriptions to configure the buttons. Additionally, the notify response from Amazon contains the subscription identifier, as well.
  2. Create a welcome e-mail. You can use the WelcomeEmail.php as a starting point.
  3. Create a new confirmation page. The example asks the user to create an entitlement password. You can customize this confirmation page.
  4. Modify the createPassword.php page to redirect the user through a URLScheme to the application [optional].

 
About Amazon Simple Pay Notifications

Amazon will contact your website whenever it has information about the subscription or payment. It will also redirect users to your website whenever they complete or abandon a subscription purchase. You must define entry points for Amazon in the subscription button definitions or provide global defaults at: Manage Co-branding of Amazon Sandboxes.
 
The following table is a very brief overview of the Amazon Simple Pay: Getting Started Guide API Version 09-17-2008.
 
Amazon Action
 
Example mapping
 
Description
 
Notify
 
/notify/index.php
 
Receives IPN notification objects during the purchase and asynchronously afterwards whenever some action happens on the user's account (i.e. renewal, cancelation, payment canceled or declined)
 
Status items used within the example are: SubscriptionSuccessful, PaymentSuccess and SubscriptionCanceled.
 
Additionally, the buyer's name and e-mail are provided along with an identifier for the type of subscription purchased.
 
Return
 
/return/index.php
 
After completing the subscription purchase, the user is redirected to this page.
 
Abandon
 
/abandon/index.html
 
The user quits the purchase experience and Amazon redirects them to this page.
 

 
Building a viewer

Next you will learn how to build a multi-issue DPS viewer with entitlement. For both the Service URL and Service Auth URL, use the $baseurl value from the settings.php file, with the extension of /api/ . For instance, if your $baseurl is http://foobar.com/dps/simplepay, set the Service URL to http://foobar.com/dps/simplepay/api/.
 
Note: For DPS v21+ iOS and all Android viewers, you have to define an integrator ID with these values. These devices ignore the values entered in Viewer Builder.
 
Once you have built and downloaded the viewer, you need to extract the account GUID for the viewer and use that value for the fulfillment_account within the settings.php file. See the "Connecting to fulfillment" section of the Build a Custom Storefront article for more details.
 

 
Testing…finally

Use the following steps to test your setup.
 
  1. Create a few folios (I recommend a minimum of three folios) within your fulfillment account. These need to be retail, public folios with corresponding iTunesConnect productIDs .
  2. Create and install a multi-issue viewer with entitlement configured as described previously.
  3. Create another sandbox account for simulating the buyer. This requires setting up another e-mail address. Once you have an e-mail address to use, configure it at
  1. Browse your application. The index.php file displays as shown in Figure 6.
Figure 6: Successful implementation of subscription options web page using sample files
Figure 6: Successful implementation of subscription options web page using sample files
 
  1. Choose any of the options above (as shown in Figure 6). You will be transferred to Amazon. Within Amazon, sign in with your new sandbox account.
  2. Confirm the purchase and Amazon takes you to the "return" page on your site.
  3. At this point, you will receive an e-mail confirmation. If you don't see it, check your spam folder.
  4. Create an entitlement password.
  5. On the device, choose "Sign In" and provide the entitlement username (your buyer sandbox e-mail address) and (entitlement) password.
  6. The most recent retail folio in your Adobe Fulfillment account is now ready for download.

 
Where to go from here

For more information and resources on using Amazon Flexible Payment Services, see the following:
 
To learn more about how to extend Adobe DPS to meet your business needs, watch the video of Klaasjan Tukker's MAX 2013 session, Extending and Integrating Digital Publishing Suite.
 
 
This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License. Permissions beyond the scope of this license, pertaining to the examples of code included within this work are available at Adobe.