Menu
Amazon DevPay
Developer Guide (API Version 2007-12-01)

Web Product Activation

Your web product must go through a process of activation before each customer can use it. This process is part of the overall process web products follow to work with Amazon DevPay (for more information, see Overall Authentication Process).

Activation means the product contacts AWS with a key identifying the customer, and AWS replies with a user token the product must use when making Amazon Simple Storage Service requests for that customer. The user token is valid only for your specific product and for the specific customer. The following sections describe how activation works.

The Activation Key

To purchase your product, the customer goes through a purchase process, which starts when the customer clicks the purchase URL (for an example of what the customer sees during the purchase process, see Appendix: The Customer Purchase Experience). At the end of this process, the customer's browser splits into two frames. The top frame contains a confirmation for the purchase. The bottom frame contains the redirect URL you provided during product registration.

When the purchase is complete, AWS generates an activation key that contains information identifying the customer and the product. The key looks similar to this: ADMAY7DVLJTWHJ76MMBMEXAMPLE.

Your web product needs the activation key in order to get the user token for the customer. The following table describes the different ways AWS makes the key available; you can use any of the ways to get the activation key.

Method Description

Displayed in the top frame of the customer's browser

AWS automatically displays the key in the top frame of the browser.

The first time the customer uses your web product, it prompts the customer to copy and paste the key from the browser window into a form the product provides.

Appended to the redirect URL

AWS automatically appends the activation key to the redirect URL as a query parameter, along with the product code.

For example, if your redirect URL is http://www.example.com/productActivation.html, the customer would be redirected to http://www.example.com/productActivation.html?ActivationKey=<activation key value>&ProductCode=<product code value>.

You have an application that retrieves the activation key and product code. This method is invisible to the customer and provides a friendlier experience. However, if you choose this method to obtain the activation key, you must design your system to handle some possible exceptions. For more information, see Exception Handling for the Redirect URL.

Provided at the activate URL

AWS provides a URL (http://www.amazon.com/dp-activate) where the customer can go to obtain a new activation key at any time (for an example of this page, see The Application Activation Page). You should display the activate URL any time you prompt the customer for the activation key. If you choose to use one of the other methods in this table, implement this one as an alternate in case the other method fails.

Activation keys expire one hour after creation for security reasons.

Important

To successfully activate your product, the activation key you provide during activation must be associated with the product token. In other words, do not provide an activation key that a customer obtained when signing up for some other product that uses DevPay besides yours. Your product should not store activation keys.

The Request for Activation

Once the application has the activation key and product code, it looks up the product token associated with the product code. The application then makes a signed request to the License Service action ActivateHostedProduct . The request must include the product token for the customer and the customer's activation key. The response includes the user token for the customer.

Note

The product calls ActivateHostedProduct to activate itself when the customer initially signs in to use the product. The product might require reactivation at other times. For more information, see Web Product Exceptions.

The requests for ActivateHostedProduct must be authenticated as follows:

  • REST-Query Requests—With an HTTPS request and an HMAC-SHA1 signature created with your Secret Access Key

    For more information and instructions, see Authentication of REST-Query Requests.

  • SOAP Requests—With an HTTPS request and a digital signature using the standard X.509 WS-Security profile

    Your product must sign the SOAP message (the body and time stamp) with your private key. The request must include your X.509 certificate in the SOAP header. For more information about calling the License Service using SOAP, see Authentication of SOAP Requests.

Storage of the User Token

The user token must be available and ready to use each time the product makes an Amazon Simple Storage Service request on behalf of the customer. We recommend your product encrypt the user token and store it securely. If the user token is ever missing, the product must get a new one. For more information, see Web Product Exceptions.

Important

It's your responsibility to design your web product so it can recognize each customer who returns to your site and retrieve the user token associated with that customer.

Exception Handling for the Redirect URL

Although the failure rate for the redirect is expected to be low, your application must be prepared to handle any failure cases. It's plausible the customer could close the browser window and prevent your application from retrieving the activation key and product code from the redirect. Your application must handle the situation in which one or both of the parameters are not available through the redirect. See the suggested actions in the following table.

Activation Key RetrievedProduct Code RetrievedSuggested Action

No

Yes

Your web page displays the name of the web product and prompts the customer for the activation key, which was displayed in the top frame of the browser window. The customer either provides the activation key from the top frame or obtains a new activation key by clicking the activate URL that you display. In either case, you need to provide a way for the customer to paste the activation key into a form on your page.

Yes

No

Your web page should display a list of your DevPay products and ask the customer to select the product just purchased (the one the activation key is associated with).

The customer can then select the product, enabling your application to retrieve the product token to use in a request for ActivateHostedProduct. If the customer chooses the wrong product, the request fails.

No

No

Your web page should display a list of your DevPay products and ask the customer to select the product just purchased (the one the activation key is associated with). The page should also prompt the customer for the activation key, which was displayed in the top frame of the browser window.

The customer can then either provide the activation key from the top frame or obtain a new activation key by clicking the activate URL that you display.

In either case, you should provide a way for the customer to paste the activation key into a form on your page.

Activation and Subscription Timing

When customers sign up for your product, they must provide a credit card. However, they're not officially subscribed until we confirm the credit card is valid (a process known as vetting). The following diagram and discussion describe the timing of when the customer is officially subscribed.

Subscription timing

When customers sign up for the product, they're redirected to your URL and receive the activation key. At that point, we start the process of vetting the card. The customer isn't yet officially subscribed to the product.

The credit card vetting process usually takes 2 minutes, but can take up to 15 minutes. During this time, your product can activate the customer and get the customer's credentials. However, until the vetting succeeds, any calls your product makes to Amazon S3 on behalf of the customer return an error saying the customer isn't signed up for Amazon S3 (the error is NotSignedUp).

When the vetting succeeds, the customer is then officially subscribed to your product. Within a few seconds, Amazon S3 begins to accept your product's requests without returning the NotSignedUp error.

Your should design your product to activate the customer and get the customer's credentials immediately after the customer is redirected to your URL. We recommend immediate activation because activation keys have a limited lifetime (one hour).

Once your product has activated the customer, it should wait until the customer is officially subscribed before sending any requests to Amazon S3. The product can determine the subscription status by polling VerifyProductSubscriptionByPid at a regular interval (e.g., 30 seconds). Until the customer is officially subscribed, the action returns false for the subscription status. For more information about the action, see VerifyProductSubscriptionByPid.

During the credit card vetting period, if customers go to their Application Billing page (at http://www.amazon.com/dp-applications), they see a message that says "Authorizing your account to access this application."

If the vetting fails, the customer receives an e-mail (see If the Validation of the Customer's Credit Card Fails). The customer needs to update the payment method with a valid card. Once the payment method is updated, we then vet the new information and switch the customer's subscription status to true (assuming the vet succeeds). For information about how customers update the payment method, see Where Customers Manage the Payment Method.