Amazon Instant Access Integration Guide. Subscriptions (SaaS)

Transcription

1 Amazon Instant Access Integration Guide Subscriptions (SaaS)

2 TABLE OF CONTENTS 1. INTRODUCTION SUBSCRIPTION PRODUCT OFFERINGS API OVERVIEW AND SPECIFICATIONS... 5 ACCOUNT LINKING ENDPOINT... 6 ACCOUNT REGISTRATION PAGE... 7 FULFILLMENT (SERVICE) ENDPOINT Subscription Activation Subscription Deactivation Subscription Update Subscription Retrieval (Get) Free Trial Subscriptions LICENSE MANAGEMENT PAGE REQUEST AUTHORIZATION IP WHITELISTING VENDOR SLA REQUEST RETRY POLICY DEVELOPER PORTAL CREATING A NEW VENDOR PROFILE FULFILLMENT INTEGRATION TESTS ACCOUNT REGISTRATION PAGE REDIRECTION TEST UPDATING AN EXISTING VENDOR PROFILE QUALITY ASSURANCE SDK DOCUMENTATION JAVA SDK C# (.NET) SDK PHP SDK RUBY SDK CUSTOMER EXPERIENCE EXAMPLE CUSTOMER FLOW SINGLE USER SUBSCRIPTIONS (SUS) EXAMPLE CUSTOMER FLOW TEAM SUBSCRIPTIONS REDIRECTING CUSTOMERS BACK TO AMAZON FAQ

3 1. INTRODUCTION Welcome to Amazon Instant Access! This guide describes the steps you, as a third-party vendor, must take to integrate with Amazon s Instant Access offerings for Software Subscriptions (SaaS). A typical integration process is pictorially represented below: Step 1 Review Integration Guide Step 2 Integrate with Amazon APIs Step 3 Enable QA Step 4 Launch on Amazon Amazon Instant Access Integration Guide Amazon.com Sign In What is your (phone for mobile accounts)? or mobile number: Payment Information Do you have an Amazon.com password? I am a new customer I am a returning customer and my password is Sign in using our secure server Amazon to include the following 4 items: ITEM 1 Cancel Save Create a developer portal account Configuration Profile Name vendorprofilename1278 Setup payment information in Developer Portal Instant Access ITEM 2 Read complete integration guide including FAQs. 1: Profile Configuration Primary address for developer portal account info@yourcompany.com 2: Integration Test 3: Account Linking Redirection Test ITEM 3 Create Product Detail Page Instant Access Link to product images or zip file 1: Profile Configuration 2: Integration Test ITEM 4 3: Account Linking Redirection Test XLS Launch on Amazon New item setup template Send Instant Access 1: Profile Configuration 2: Integration Test 3. Account Linking Redirection Test Amazon create ticket for QA Push to production QA QA takes about 2 weeks Your profile has been saved successfully. After reviewing this guide (Step 1 in the diagram), you must create an account on Amazon Developer Portal and build a web service to communicate with our Instant Access platform using the API discussed later. Our business team (softwaresaas@amazon.com) will then follow up and go through QA before launching the product detail page on the Amazon website. The integration process typically takes around 2 3 days with additional 7 10 days for testing. Please contact d3-support@amazon.com at any time for assistance and include the company name in the subject line to make tracking easier. 3

4 2. SUBSCRIPTION PRODUCT OFFERINGS There are 2 categories of subscription products that may be offered to the customers through Amazon Instant Access: 1. Single User Subscription (SUS): This category targets customers who purchase software meant for individual use. Customers can purchase subscriptions, cancel subscriptions and set up renewal options on the Amazon website. Each SUS purchase results in one subscription for a single user. 2. Team Subscription: This category targets customers who purchase software meant for teams, where the software would typically allow users to collaborate with their colleagues and perform group activities. Contrary to SUS, each team subscription contains one or more licenses assignable to multiple users. Customers can purchase subscriptions, cancel subscriptions, set up renewal options, and purchase additional licenses for subscriptions on the Amazon website. You must provide an external web page where customers can assign and un-assign the licenses to users (more details provided in the LICENSE MANAGEMENT PAGE section later). If applicable, all role management-related functions should be provided through the page as well. 4

5 3. API OVERVIEW AND SPECIFICATIONS When a customer performs a key action on the Amazon website such as purchasing a subscription, we send you an HTTP request with a JSON payload to notify you of the event. Depending on the customer s action and whether the product is an SUS or Team Subscription, the content of the payload varies. You must set up a web service to receive these incoming requests, adjust the offerings to the customers accordingly, and return HTTP responses per specification. This communication is designed to be completely synchronous. To help with the implementation, we provide SDKs in the following programming languages (more details provided in the SDK DOCUMENTATION section later): Product Type Single User Subscriptions (SUS) Team Subscriptions Supported Programming Languages Java, Ruby,.Net and PHP Java and Ruby Here is an overview of the API endpoints and web pages your service must support: Account Linking Endpoint: This endpoint links the customers Amazon accounts with their third-party vendor accounts. We prompt the customers for one or more account-identifying information fields for your software/website such as username or . The fields are configured during vendor on-boarding (more details provided in DEVELOPER PORTAL section later). We send you the field values, and you send back the user ID. Account Registration Page: To facilitate account linking, you must provide an external registration page where customers can create new accounts (or login with their existing ones) for your software/website. When a customer initiates the one-time setup process to activate a new subscription, we display your page in a 600 x 500 popup window. The page must redirect back to the Amazon website after the registration is complete. Fulfillment (Service) Endpoint: This endpoint is for fulfilling purchases. For SUS products, we call this endpoint when a customer activates or deactivates a product. For Team Subscription products, we call this endpoint in the following scenarios: o o o o o A customer activates a new subscription An active subscription is cancelled New licenses are added to an existing subscription License details for a subscription need to be displayed Unassigned licenses need to be removed during subscription renewal License Management Page: This page is for Team Subscription products only. You must provide an external web page to let customers assign and un-assign licenses for your product. The page must not allow activities which affect billing (e.g. changing the number of licenses tied to subscriptions, cancelling subscriptions, renewing subscriptions or licenses). Instead, we recommend using links redirecting back to the Amazon website (see REDIRECTING CUSTOMERS BACK TO AMAZON for more details). The URLs and endpoints are set during vendor on-boarding (more details provided in DEVELOPER PORTAL section later). You must use HTTPS and have a valid SSL certificate issued by a trusted certificate authority. We recommend purchasing the certificate from reputable sources like GoDaddy, DigiCert, Comodo and Symantec. To verify whether your SSL certificate is valid, use an online tool such as like this one: Note: Please avoid certificates from Let s Encrypt as we do not recognize them currently. In the next few pages, we cover the required components of the web service in more detail. We also go over the vendor SLAs, request authentication and retry policies. 5

6 ACCOUNT LINKING ENDPOINT This endpoint links the customers Amazon accounts with their third-party vendor accounts. We prompt the customers for one or more account-identifying information fields for your software/website such as username or . Once we obtain the fields, we send to the endpoint an HTTP POST request with a JSON payload containing the following fields: Field Type Required Description operation String Yes The name of the operation. The value is always set to GetUserId in this case. infofield1 String Yes The username or other account identifier. This field is required. infofield2 String No An optional second identifier field configured by the vendor. infofield3 String No An optional third identifier field configured by the vendor. You must always return a response with a status code 200 (any other code is regarded as a failure) and a JSON body containing the following fields: Field Type Required Description response String Yes Valid response values are: OK FAIL_ACCOUNT_INVALID userid String Yes The immutable ID on the vendor side for subsequent fulfillment API calls. Example HTTP POST request from Amazon to your service: { "operation": "GetUserId", "infofield1": "john.doe@example.com", "infofield2": "MyGameCharacter" Response from your service back to Amazon: { "response": "OK", "userid": "550e8400" Health Check Every five minutes, we call the account linking endpoint with dummy values to see if your service is running. This ensures the products on our detail pages are purchasable. Please note the extra load these periodic calls may place on the endpoint. The health check sends an HTTP POST request with the following JSON payload: { "operation":"getuserid", "infofield1": "TESTVALUE" To pass the health check, your service must return a status code 200 with an OK response. The userid field is ignored. If we do not receive the expected response, we assume the service is down and make the products unavailable for purchase by disabling the buy button. We also send an alert to the all-hours support address set during the initial vendor on-boarding. If the health check succeeds at a subsequent point, we automatically make the product available for purchase again, and send a success notification . 6

7 ACCOUNT REGISTRATION PAGE To facilitate account linking, you must provide an external registration page where the customers can create new accounts (or login with their existing ones) for the third-party software/website. When a customer initiates the one-time setup required before using a new subscription, we display the page to the customer in a 600 x 500 popup window. Once the account registration is complete, the page must redirect the customer back to the redirection URL which we provide in the query string. The page must also append to the redirection URL up to three account-identifying information fields using the infofield1, infofield2 and infofield3 query parameters. Example Here is a sample account registration page URL: We open the page and provide our redirection URL in the query string (note the URL encoding): The value of redirecturl query parameter must be decoded: https%3a%2f%2famazon.com%3frequestid%3d1%26subid%3d2 The redirection URL may already contain some query parameters such as requestid and subid. These parameters are subject to change and must not be altered in any way. Append the account-identifying info fields to the query string: Here are some important notes: Minimum of one account-identifying information field is required. This means infofield1 is mandatory. The values for the information fields must be URL encoded: o o Good: &infofield1=john%40example.com Bad: &infofield1=john@example.com The information fields must be appended to the query string in the same order as what was configured during the initial on-boarding step (more details provided in the CREATING A NEW VENDOR PROFILE section later). 7

8 FULFILLMENT (SERVICE) ENDPOINT The fulfillment endpoint is for multiple fulfillment operations. For SUS products, we call this endpoint whenever a customer activates or deactivates a product. For Team Subscription products, we call this endpoint in the following scenarios: o o o o o A customer activates a new subscription An active subscription is cancelled New licenses are added to an existing subscription License details for a subscription need to be displayed Unassigned licenses need to be removed during subscription renewal The content of the request payload differs depending on the operation and the product type. The following operations must be supported: subscription activation, deactivation, retrieval (get) and update. 1. Subscription Activation We send a subscription activation (HTTP POST) request to the fulfillment endpoint when a customer initiates the onetime setup process required for using the newly purchased subscription. The JSON request payload contains the following fields: Field Type Required For Description operation String SUS, Team Subs The name of the operation. SubscriptionActivate in this case. subscriptionid String SUS, Team Subs A unique identifier for the subscription. productid String SUS, Team Subs The third-party product code identifying the item fulfilled. In most cases this would the vendor SKU. userid String SUS, Team Subs Customer ID identifying the user to deliver the item to. This is the same ID you send on account linking calls. numberoflicenses Integer Team Subs only The number of licenses in the subscription the customer has access to. This number may change later as customers add or remove licenses. You must always return a response with a status code 200 (any other code is regarded as a failure). The response body must indicate whether the activation was successful and contain the following fields: Field Type Required For Description response String SUS, Team Subs Valid response values are: OK FAIL_USER_NOT_ELIGIBLE User is not eligible to purchase this item FAIL_USER_INVALID User is invalid FAIL_INVALID_SUBSCRIPTION Invalid values are in the JSON fields subscriptionid or numberoflicenses FAIL_OTHER This is a catch-all error code As the API evolves, more response values will be added and the generic value FAIL_OTHER will be used less and less. numberofunusedlicenses Integer Team Subs only The number of licenses assigned to users. numberofusedlicenses Integer Team Subs only The number of licenses currently un-assigned. managementurl String Team Subs only The URL to the license management page. See LICENSE MANAGEMENT PAGE section for more details. 8

9 Example HTTP POST request from Amazon to your service for an SUS product: { "operation": "SubscriptionActivate", "subscriptionid": "V7ZX0EWJDAYPXD9FS941", "productid": "product_a", "userid": "550e8400", Response from your service back to Amazon: { "response": "OK" HTTP POST request from Amazon to your service for a Team Subscription product: { "operation": "SubscriptionActivate", "subscriptionid": "V7ZX0EWJDAYPXD9FS941", "productid": "product_a", "userid": "550e8400", "numberoflicenses": 4, Response from your service back to us: { "response": "OK", "numberofunusedlicenses": 1, "numberofusedlicenses": 2, "managementurl": " Once a subscription is successfully activated, the customer is given a link to your management page for assigning or unassigning licenses. The page must not allow activities which affect billing (e.g. changing the license quantity, cancelling subscriptions). More details are provided in the LICENSE MANAGEMENT PAGE section later. 9

10 2. Subscription Deactivation We send a deactivation (HTTP POST) request to the fulfillment endpoint when a subscription is cancelled. You must revoke all licenses tied to the subscription, and return a response indicating whether the operation was successful. The request has a JSON payload with the following fields: Field Type Required Description operation String Yes The name of the operation. SubscriptionDeactivate in this case. subscriptionid String Yes A unique identifier for the license. This is the same ID as the one Amazon sent in subscription activation calls. period String Yes An enumerated value representing the period of a subscription s life cycle in which this action occurred. Valid values are: GRACE_PERIOD Action occurred during the risk-free period. REGULAR Action occurred while the subscription was valid. NOT_STARTED The subscription was purchased but not activated. This is used when the UNABLE_TO_FULFILL reason code is used. (See the reason field below). FREE_TRIAL Used for free trial subscriptions. reason String Yes An enumerated value explaining why this message was sent. Valid values are: NOT_RENEWED The subscription reached the end of its term. USER_REQUEST The user deactivated the subscription via Amazon.com. CUSTOMER_SERVICE_REQUEST Deactivation initiated by Amazon Customer Service. PAYMENT_PROBLEM Deactivation initiated due to an error in processing the customer s payment. UNABLE_TO_FULFILL Subscription was canceled due to a problem activating the subscription. TESTING Test request, please ignore. You must always return a response with a status code 200 (any other code is regarded as a failure). The response body must indicate whether the deactivation was successful and contain the following fields: Field Response Description Valid response values are: OK FAIL_INVALID_SUBSCRIPTION subscriptionid is not recognized FAIL_OTHER This is a catch-all error code Example HTTP POST request from Amazon to your service: { "operation": "SubscriptionDeactivate", "subscriptionid":"v7zx0ewjdaypxd9fs941" "period": "GRACE_PERIOD", "reason": "CUSTOMER_SERVICE_REQUEST", Response from your service back to Amazon: { "response": "OK" 10

11 3. Subscription Update This operation is for Team Subscriptions only. We send an update (HTTP POST) request to your fulfillment endpoint when the license quantity of a subscription must be changed. This occurs in the following scenarios: o o A customer purchases one or more additional licenses for an active subscription, and we send an update request to increment the license quantity on your end. During the renewal of a subscription, we discover that the subscription has one or more unassigned licenses. We automatically send you an update request to remove unassigned licenses on your end to avoid unnecessary charges to the customer. Customers can add back the licenses any time they want on the Amazon website. The JSON request payload contains the following fields: Field Type Required Description operation String Yes The name of the operation. SubscriptionUpdate in this case. subscriptionid String Yes A unique identifier for the subscription. productid String Yes The third-party product code identifying the item fulfilled. In most cases this would the vendor SKU. userid String Yes Customer ID identifying the user to deliver the item to. This is the same ID you send on account linking calls. numberoflicenses Integer No The updated number of total licenses associated with the given subscription. Any new license must be initialized in an unassigned (assignable) state. This parameter is mutually exclusive with removeallunassignedlicenses. removeallunassignedlicenses Boolean No A boolean flag to indicating whether un-assigned licenses should be removed. Mutually exclusive with numberoflicenses. You must always return a response with a status code 200 (any other code is regarded as a failure). The response body must indicate whether the update was successful and contain the following fields: Field Type Required Description response String Yes Valid response values are: OK FAIL_USER_NOT_ELIGIBLE User is not eligible to purchase this item FAIL_USER_INVALID User is invalid FAIL_INVALID_SUBSCRIPTION Invalid values provided in the JSON fields subscriptionid, numberoflicenses, removeallunassignedlicenses FAIL_OTHER This is a catch-all error code As the API evolves, more response values will be added and the generic value FAIL_OTHER will be used less and less. numberofunusedlicenses Integer Yes The number of licenses assigned to users. numberofusedlicenses Integer Yes The number of licenses currently un-assigned. managementurl String Yes The URL to the license management page. See LICENSE MANAGEMENT PAGE section for more details. 11

12 Example A customer owns a subscription with ID V7ZX0EWJDAYPXD9FS941. The subscription has a total of 7 licenses: 5 assigned and 2 unassigned. The customer buys 2 more licenses for the subscription on Amazon.com, and we send you an HTTP POST request to increase the total license count of the subscription by 2: { "operation": "SubscriptionUpdate", "subscriptionid": "V7ZX0EWJDAYPXD9FS941", "productid": "product_a", "userid": "550e8400", "numberoflicenses": 9, // Response from your service back to us should look something like this: { "response": "OK", "numberofunusedlicenses": 4, // "numberofusedlicenses": 5, "managementurl": " Note: Only the value of numberofunusedlicenses should increase, as the new licenses are not assigned yet. The sum of numberofunusedlicenses and numberofusedlicenses must equal numberoflicenses. Your service is responsible for calculating the new values. Here are simple equations clarifying how: 1. oldnumberoflicenses = oldnumberofunusedlicenses + oldnumberofusedlicenses 2. numberoflicensesincrease = newnumberoflicenses - oldnumberoflicenses 3. newnumberofunusedlicenses = oldnumberofunusedlicenses + numberoflicensesincrease 4. newnumberofusedlicenses = oldnumberofusedlicenses If we apply the above equations to this example we get the following: 1. oldnumberoflicenses = = 7 2. numberoflicensesincrease = 9 7 = 2 3. newnumberofunusedlicenses = = 4 4. newnumberofusedlicenses = 5 After the billing period, the renewal process for subscription V7ZX0EWJDAYPXD9FS941 will kick in. At that point we would notice that the subscription still has 4 unassigned licenses. To avoid charging the customer extra for the next billing cycle, we send you an HTTP POST request to clean up the unassigned licenses from the subscription: { "operation": "SubscriptionUpdate", "subscriptionid": " V7ZX0EWJDAYPXD9FS941", "productid": "product_a", "userid": "550e8400", "removeallunassignedlicenses": true, Response from your service back to us: { "response": "OK", "numberofunusedlicenses": 0, "numberofusedlicenses": 5, "managementurl": " Note: While removing licenses, numberofusedlicenses should remain unchanged and numberofunusedlicenses should become 0. 12

13 4. Subscription Retrieval (Get) This operation is for Team Subscriptions only. We send a retrieval (HTTP POST) request to the fulfillment endpoint whenever we need to pull up the most recent license information on a subscription, such as the count of assigned/unassigned licenses and the license management URL. The JSON request payload contains the following fields: Field Type Required Description operation String Yes The name of the operation. SubscriptionGet in this case. subscriptionid String Yes A unique identifier for the subscription. productid String Yes The third-party product code identifying the item fulfilled. In most cases this would the vendor SKU. userid String Yes Customer ID identifying the user to deliver the item to. This is the same ID you send on account linking calls. You must always return a response with a status code 200 (any other code is regarded as a failure). The response body must indicate whether the update was successful and contain the following fields: Field Type Required Description response String Yes Valid response values are: OK FAIL_USER_INVALID User is invalid FAIL_INVALID_SUBSCRIPTION Invalid values provided in the JSON field subscriptionid FAIL_OTHER This is a catch-all error code As the API evolves, more response values will be added and the generic value FAIL_OTHER will be used less and less numberofunusedlicenses Integer Yes The number of licenses assigned to users. numberofusedlicenses Integer Yes The number of licenses currently un-assigned. managementurl String Yes The URL to your license management page. See LICENSE MANAGEMENT PAGE section for more details. Example HTTP POST request from Amazon to your service: { "operation": "SubscriptionGet", "subscriptionid": "V7ZX0EWJDAYPXD9FS941", "productid": "product_a", "userid": "550e8400" Response from your service back to Amazon: { "response": "OK", "numberofunusedlicenses": 4, "numberofusedlicenses": 5, "managementurl": " 13

14 5. Free Trial Subscriptions We allow free trials for both SUS and Team Subscription products by not charging the customers for a set period of time after activation (e.g. 30-days free trial). Free trial subscription activation calls look identical to regular paid subscription activation calls. When the trial period is over, we automatically roll-over the customers to a pre-configured paid subscription plan (e.g. monthly or annually) unless the customers have auto-renewal turned off for the product. The auto-renewal is enabled by default. If the auto-renewal is active and the roll-over occurs, we begin charging the customers. You specify the paid plan a free trial rolls over to with our business team during the initial vendor on-boarding. Currently, there is no way for vendors to distinguish free trial subscription activation calls from paid ones. Our business team periodically sends reports showing the breakdown of free-trials vs. paid subscriptions. Example 1. When a customer activates free trial, we send you a subscription activation (HTTP POST) request as usual: { "operation": "SubscriptionActivate", "subscriptionid": "US-7d3001e b7-a a548d8", "productid": "product_a", "userid": "550e8400", 2. The response your service sends back to Amazon: { "response": "OK" 3. Once the trial period is over, we begin charging the customer automatically. No requests are sent to the vendor at this point. When a customer deactivates a free trial subscription before the trial period ends, the automatic roll-over does not occur. In this case, we send a subscription deactivation (HTTP POST) request where the period field is set to FREE_TRIAL. Example 1. We send your service a subscription deactivation (HTTP POST) request with the period set to FREE_TRIAL : { "operation": "SubscriptionDeactivate", "subscriptionid":"us-7d3001e b7-a a548d8" "period": "FREE_TRIAL", "reason": "USER_REQUEST", 2. The response from your service back to Amazon: { "response": "OK" 14

15 LICENSE MANAGEMENT PAGE This page is required for Team Subscription products only. You must provide an external web page allowing customers to assign and un-assign licenses to users. The design of this page is completely up to you, but the page must not allow customers to perform activities which affect billing (e.g. changing the number of licenses tied to subscriptions, cancelling subscriptions, renewing subscriptions or licenses). Instead, we recommend using links redirecting back to our Amazon website (see REDIRECTING CUSTOMERS BACK TO AMAZON for more details). We send a subscription retrieval request to your fulfillment endpoint in order to obtain the URL for your license management page to relay to the customer. Here is an example URL: 15

16 REQUEST AUTHORIZATION To allow verification of whether Amazon is the initiator of an API calls, a signature is provided in the headers of all account linking and fulfillment requests. The header fields are as follows: Header Field Authorization Description This field is populated with the information needed to authenticate the request and consists of an HMAC style signature and the information to calculate it. This field breaks down as follows: ALGORITHM SignedHeaders=SIGNEDHEADERS, Credential=CREDENTIAL, Signature=SIGNATURE x-amz-request-id x-amz-date x-amz-customer-id x-amz-dta-version ALGORITHM: The algorithm for signing messages. This is always set to DTA1-HMAC-SHA256. SIGNEDHEADERS: List of signed headers names lowercased and then sorted in byte order. CREDENTIAL: This is in format {KEY/{DATE, where KEY is the public identifier for the secret key used to sign. DATE is the date of the full time presented in x-amz-date in UTC. Using this information secret daily key for the request is calculated. The calculation is done by signing the Date string in format YYYYMMDD with the secret key. The secret daily key is then used for the rest of the signing. SIGNATURE: The computed signature using the request path, query parameters, HTTP method, signed headers and body. The algorithm is the same as used in: with these major differences: o The keys are only generated to the *day* level as the Instant Access system is a single service segmented by region, and thus secret keys are already unique to this level o The signing key is the HMAC-256 of the secret and the x-amz-date header (none of the other region, service, etc. information is required) o The header names and values must not be trimmed, lowered, or otherwise modified when creating the canonical headers A unique message ID The time of the request. Best practice is to discard any messages more than 30 minutes old. A directed customer ID for the Amazon customer The API version Example Authorization: DTA1-HMAC-SHA256 SignedHeaders=content-type;x-amz-date;x-amz-customer-id;x-amz-dtaversion;x-amz-request-id, Credential=69b2048d-8bf8-4c1c-b49d-e a9a5/ , Signature=ced6826de92d2bdeed8f846f0bf508e8559e98e4b b84c54174deb456c x-amz-request-id: 0A49CE EAC x-amz-date: T233600Z x-amz-customer-id: x-amz-dta-version: 1 content-type: application/json This page should serve only as a reference, as the SDKs automatically handle the authorization. You simply need to specify, in the SDK code, the public and private key pair we generate for you. We cover how to trigger the key generation in DEVELOPER PORTAL section, and how to use it in the SDK DOCUMENTATION section later. Note: Please review your server setup and ensure that the Authorization header is not stripped away. For example, Apache does not, by default, pass authorization headers to PHP unless the user explicitly allows it in its configuration file. 16

17 IP WHITELISTING The request authorization is already built-in to the Instant Access API. As such, IP whitelisting for the purpose of authentication is almost always unnecessary. If you still choose to use it for your service, The IP ranges used by Amazon are available in JSON form from here. You should expect these IP ranges to change several times a week. As such, your web service must poll the list of IP ranges and update the whitelist accordingly, as described in the linked documentation. VENDOR SLA To provide the best experience possible to the customers, we expect all vendors to uphold the following SLAs (Service Level Agreements) for their web services: For account-linking and subscription get API calls: 50% of all responses should occur within 1 second 99% of all responses should occur within 5 seconds For subscription activation, deactivation and update API calls: 50% of all responses should occur within 5 seconds 99% of all responses should occur within 15 seconds. REQUEST RETRY POLICY When API calls to your web service fail for any reason, we handle them in the following manner: If an account-linking API call fails, error messages are displayed to customers who can make the decision to retry as many times as they would like. If a subscription activation call fails, error messages are displayed to customers who can make the decision to retry as many times as they would like. If a subscription deactivation call fails, then we make a series of rapid-fire requests. If all requests failed, the subscription marked as deactivated on our side. The subscription may not be deactivated on your end. For Team Subscription only: If a subscription update call fails while adding new licenses, error messages are displayed to the customers who can make the decision to retry as many times as they would like. If a subscription update call fails while removing unassigned licenses (during subscription renewal), the customers is charged for the unassigned licenses until the next cycle. If a subscription retrieval (get) API call fails, we display to the customers the cached and possibly outdated values of the license quantities. We display your license management URL to redirect the customers so they can see the latest license details if needed. 17

18 4. DEVELOPER PORTAL In addition to building a web service, you must sign up for a developer account on Amazon Developer Portal and create a vendor profile. This requires the profile name, URLs for your web service, account-identifying information fields, and all-hours support address. In order to finalize the profile, you must also pass a set of automated tests within the developer portal. The tests ensure your web service supports the API per specification, and help resolve any networking or security issues. The tests consist of two parts: fulfillment integration tests and account registration page redirection test. These are not full end-to-end tests (they occur during QA). 18

19 CREATING A NEW VENDOR PROFILE Below is a summary of the steps required to create a new vendor profile: 1. Create new account on developer portal: Go to and click Sign In at the top right of the page. Follow the instructions to create a new developer account. 2. Go to the Amazon Instant Access page: Go back to and login with the new account. Click on APPS & SERVICES and then on PC/Mac & Web Instant Access. 3. Configure a new vendor profile: Go to Step 1: Profile Configuration. Enter the name for the new profile. Enter the URLs for your web service. Enter the all-hours support . Enter up to 3 account-identifying information fields. The first field is mandatory. Click on Submit. An authorization key pair should be generated at this point. Click on Show Keys to access the key pair. Keep the private key in a secure location. 4. Enable request authorization in your service using the generated key pair: Follow the SDK-specific instructions (see SDK DOCUMENTATION) for more details on this part. At this point your web service should be running and ready for end-to-end testing. 5. Run the integration tests: Click on Step 2: Integration Test. Select Single User Subscriptions or Team Subscriptions (depending on your product type) in the Test Suite dropdown. Enter the account-identifying information fields to be used for testing. Click on Run Test (this button is disabled until the profile configuration is complete). If there are any issues, resolve them and rerun the tests until everything passes. 6. Run the registration page redirection test: Click on Step 3: Account Linking Redirection Test. Click on Begin Redirection Test (this button is disabled until the integration tests pass). This should redirect to your own registration page in a popup window. Complete the registration and verify that the popup window is closed and you are redirected back. If there are any issues, resolve them and rerun the test until it passes. 7. Finalize the profile creation: Once all the tests pass, the Save Profile button at the bottom should be enabled. Click on Save Profile to finalize the profile creation. Follow the instructions on the following popup window (see QUALITY ASSURANCE). Please do not create multiple vendor profiles with the same name to avoid confusion in the future. 19

20 FULFILLMENT INTEGRATION TESTS The integration tests check account linking, subscription activation, subscription deactivation, subscription get and subscription update API calls. The following test scenarios are run to see if the fulfillment integration has been successfully carried out: Test Case Account linking with valid user: We send you one account linking request with the account-identifying information fields (e.g. ) set in the test page. Account linking duplicate call with same valid user: We send you two duplicate account linking requests with the account-identifying information fields (e.g. ) set in the test page. Account linking with invalid user: We wend you one account linking request with all three account-identifying information fields set to string value DTG_INVALID_USER_INFO. Subscription activation with valid user and valid product: We send you one valid account linking request to get a user ID. Then we send you one subscription activation request with the user ID, random subscription ID, and the product ID set in the test page. Subscription activation twice with valid user and valid product: We send you one valid account linking request to obtain a userid. Then we send you two duplicate subscription activation requests with the userid, random subscription ID, and the product ID set in the test page. The same subscription ID is sent for both requests. Subscription activation for invalid user: We send you one subscription activation request with an invalid user ID with prefix invaliduserid, random subscription ID, and the product ID set in the test page. Subscription activation for invalid product: We send you one valid account linking request to obtain a user ID. Then we send you one subscription activation request with the user ID, random subscription ID, and an invalid product ID with string value DTG_INVALID_PRODUCT_ID. Subscription deactivation for valid user and valid product: We send you one valid account linking request to get a user ID. Then we send you valid subscription activation request with the user ID, random subscription ID, and the product ID you set in the test page. Then we send you a subscription deactivation request for the same subscription ID. Subscription deactivation twice: We send you one valid account linking request to get a user ID. Then we send you one valid subscription activation request with the user ID, random subscription ID, and the product ID set in the test page. Then we send you two duplicate subscription deactivation requests for the same subscription ID. Subscription get for valid user and valid product (Team Subscription only): We send you one valid account linking request to get a user ID. Then we send you a valid subscription activation request with the user ID, random subscription ID, and the product ID set in the test page. Then we send you a subscription get request with the same subscription ID. Subscription get after deactivation for valid user and valid product (Team Subscription only): We send you one valid account linking request to get a user ID. Then we send you a valid subscription activation request with the user ID, random subscription ID, and the product ID set in the test page. Then we send you a subscription deactivation request for the same subscription ID. Then we send you a subscription get request with the same subscription ID. Subscription update for valid user and valid product (Team Subscription only): We send you one valid account linking request to get a user ID. Then we send you a valid subscription activation request with the user ID, random subscription ID, and the product ID set in the test page. Then we send you a subscription update request for the same subscription ID to increment the license quantity. 20 Expected Behavior The response should be OK and the user ID mapping to the account-identifying information fields should be returned. The response should be OK and the user ID mapping to the account-identifying information fields should be returned for both requests. The number of requests should not affect the user ID returned. The response field should be FAIL_ACCOUNT_INVALID. The user ID field should be set to null or an empty string. In order for this test to be meaningful, you should not implement separate logic around string value DTG_INVALID_USER_INFO just to pass the test. The response should be OK and you should fulfill the item for the correct user. The response should be OK and your service should recognize the subscription is already active and act accordingly for the second request (e.g. log the event but do nothing). The response should be FAIL_USER_INVALID. In order for this test to be meaningful, you should not implement separate logic around prefix invaliduserid just to pass the test. The response should be FAIL_OTHER. In order for this test to be meaningful, you should not implement separate logic around string value DTG_INVALID_PRODUCT_ID just to pass the test. The response should be OK and the subscription should be deactivated on your end. The response should be OK. Your web service should recognize the subscription is already deactivated and act accordingly for the second request (e.g. log the event but do nothing). The response should be OK and the correct subscription mapping to the subscription ID should be returned. The response should be FAIL_INVALID_SUBSCRIPTION. The response should be OK and the subscription s number of unused licenses should be increased by the correct amount. Some test cases send multiple requests, but the results table in the test page displays details of the last request only. All test cases are independent from each other.

21 ACCOUNT REGISTRATION PAGE REDIRECTION TEST This test checks the customer s ability to register a new account with your registration page, and to ensure it redirects back to us with correct query parameters. Once the test is initiated, a popup window opens displaying the registration page. If the window does not show the correct location, correct the value in Account Registration URL textbox. Register a new account in the registration page. If registration takes longer than two minutes, the window times out and the test fails. If your configuration is correct, the window should automatically close. If the test is not successful, check the Test Results section for advice on resolving the issue. UPDATING AN EXISTING VENDOR PROFILE Below is a summary of the steps required to update an existing vendor profile: 1. Go to the Amazon Instant Access page: Go to and login with the existing account. Click on APPS & SERVICES and then on PC/Mac & Web Instant Access. 2. Update the vendor profile: Go to Step 1: Profile Configuration. Select the profile to update in Configuration Profile dropdown. Make any necessary changes to the profile. The authentication key pair cannot be changed once generated. If the private key was compromised, contact d3-support@amazon.com. 3. Run the integration tests: Click on Step 2: Integration Test. Select Single User Subscriptions or Team Subscriptions (depending on your product type) in the Test Suite dropdown. Enter the account-identifying information fields to be used for testing. Click on Run Test (this button is disabled until the profile configuration is complete) If there are any issues, resolve them and rerun the tests until everything passes. 4. Run the registration page redirection test: Click on Step 3: Account Linking Redirection Test. Click on Begin Redirection Test (this button is disabled until the integration tests pass) This should redirect to your own registration page in a popup window. Complete the registration and verify that the popup window is closed and you are redirected back. If there are any issues, resolve them and rerun the test until it passes. 7. Finalize the profile update: Once the tests pass, the Save Profile button at the bottom should be enabled. Click on Save Profile to finalize the profile update. The instructions in the popup window is only for first time creation and can be ignored. Note: The integration tests and the registration page direction test must re-run after any change to the vendor profile. 21

22 QUALITY ASSURANCE After finalizing the profile on the Amazon Developer Portal, you must submit for QA the following information to The name of the vendor profile on the Instant Access page. The primary address of the Amazon Developer Portal account. A link or zip file containing the image assets including a company logo, main product image and up to 6 additional supporting images. Please follow the video and image guidelines here. Completed NIS (New Item Setup) excel sheet found here. An example can be found here. If applicable, details on any free trial plans to set up (this is for Team Subscription products only). Please include the length of the trial period and the paid plan to roll over to if there are multiple options. 22

23 5. SDK DOCUMENTATION The SDK itself has more detailed documentation on individual functionality. This section has brief information as an introduction. Please ignore the naming convention such as DTA (short for Direct to Account ) and interfaces in the SDK codebase such as FulfillPurchase and RevokePurchase as they serve a different product. JAVA SDK The Java SDK includes two servlets, AccountLinkingServlet and PurchaseServlet. The AccountLinkingServlet supports the account linking API call. The PurchaseServlet supports SubscriptionActivate, SubscriptionDeactivate, SubscriptionGet and SubscriptionUpdate API calls. Both servlets need a credential store with a valid key, provided during the profile configuration in the developer portal. The SDK can be found on GitHub Credential Store A CredentialStore is needed for request authorization. /* * Class used to manage the credential */ public class CredentialStore { private HashMap<String, Credential> store; public CredentialStore() { store = new HashMap<String, Credential>(); The getcredentialstore function must return a valid CredentialStore object. /** * Returns the credential store * a CredentialStore object with the credential */ public abstract CredentialStore getcredentialstore(); This object can be built from: A file with the credential pairs An InputStream A String. If a credential file is used, it must contain a secret key and a public key separated by a space as follows: 69b2048d-8bf8-4c1c-b49d-e a9a5 dce f ad28-0e1ab

24 Account Linking In order to implement the Account Linking API using the SDK, extend the AccountLinkingServlet and implement one abstract method GetUserId. /** * Process the request and returns the user id * request: the request relative to the get user id operation a GetUserIdSerializableResponse object */ public abstract GetUserIdSerializableResponse getuserid(getuseridserializablerequest request); Subscription Activate In order to implement the Subscription Activate API using the SDK, extend the PurchaseServlet class and implement one abstract method processsubscriptionactivate. /** * Process the activation request and return the response to whether or not the request succeeded * request: the request with information about the subscription a SubscriptionResponse object */ public abstract SubscriptionResponse processsubscriptionactivate(subscriptionactivaterequest request); Subscription Deactivate In order to implement the Subscription Deactivate API using the SDK, extend the PurchaseServlet class and implement one abstract method processsubscriptiondeactivate. /** * Process the deactivation request and return the response to whether or not the request succeeded * request: the request with information about the subscription a SubscriptionResponse object */ public abstract SubscriptionResponse processsubscriptiondeactivate(subscriptiondeactivaterequest request); Subscription Get In order to implement the Subscription Get API using the SDK, extend the PurchaseServlet class in package com.amazon.dtasdk.v3.servlets and implement one abstract method processsubscriptionget. /** * Process the get request and return the response to whether or not the request succeeded * request: the request with information about the subscription a SubscriptionGetResponse object */ public abstract SubscriptionGetResponse processsubscriptionget(subscriptiongetrequest request); Subscription Update In order to implement the Subscription Update API using the SDK, extend the PurchaseServlet class in package com.amazon.dtasdk.v3.servlets and implement one abstract method processsubscriptionupdate. /** * Process the update request and return the response to whether or not the request succeeded * request: the request with information about the subscription a SubscriptionResponse object */ public abstract SubscriptionResponse processsubscriptionupdate(subscriptionupdaterequest request); 24

25 C# (.NET) SDK The C# (.NET) SDK currently does not support Team Subscriptions. The documentation below is only for SUS. The C# SDK includes two controllers, AccountLinkingController and PurchaseController. The AccountLinkingController supports the account linking API call. The PurchaseController supports the ProcessSubscriptionActivate and ProcessSubscriptionRevoke API calls. Both controllers need to implement the CredentialStore object with a valid key, provided during the profile configuration in the developer portal. The SDK can be found on GitHub Credential Store An overridden CredentialStore object needed for authenticating messages. It must be implemented in both controllers. protected override CredentialStore CredentialStore { get; = new CredentialStore("private_key", "pub_key"); The CredentialStore object must be initialized. Ensure the parameters are entered in the right order. The abstract controller methods then handle all signature verification automatically. Account Linking In order to implement Account Linking API using the SDK, extend the controller class AccountLinkingController and implement one abstract method GetUserId. /// <summary> /// Processes getuserid requests. /// </summary> /// <returns>a <see cref="task{t"/> of <see cref="getuseridresponse"/></returns> protected override Task<GetUserIdResponse> GetUserId(GetUserIdRequest request); Subscription Activation To implement the Subscription Activation API using the SDK, extend the PurchaseController class and implement one abstract method ProcessSubscriptionActivate. /// <summary> /// Processes Subscription Activation requests. /// </summary> /// <returns>a <see cref="task{t"/> of <see cref="subscriptionresposne"/> or an exception if bill once purchases are not supported.</returns> protected override Task<SubscriptionResponse> ProcessSubscriptionActivate(SubscriptionActivateRequest request); Subscription Deactivation To implement the Subscription Deactivation API using the SDK, extend the PurchaseController class and implement one abstract method ProcessSubscriptionRevoke. /// <summary> /// Processes Subscription Revoke (Deactivate) requests. /// </summary> /// <returns>a <see cref="task{t"/> of <see cref="subscriptionresponse"/> or an exception if bill once purchases are not supported.</returns> protected override Task<SubscriptionResponse> ProcessSubscriptionRevoke( SubscriptionDeactivateRequest request); 25

26 PHP SDK The PHP SDK currently does not support Team Subscriptions. The documentation below is only for SUS. The PHP SDK includes two controllers, AccountLinkingController and PurchaseController. Each controller is stood up on a separate endpoint. The AccountLinkingController supports the account linking API call. The PurchaseController supports the subscription activation and deactivation API calls. Both controllers need a credential store with a valid key, provided during profile configuration in the developer portal. The controller s lifecycle is as follows: 1. Controller is created by passing a valid CredentialStore. 2. Callbacks are assigned to the corresponding operations. 3. Function process is called passing the $_SERVER variable, where the request is validated and the proper callback is called. 4. The return of process is sent as a response. 5. Controller is destroyed. When using the controllers, ensure the response does not send any other extraneous information. The SDK can be found on GitHub Credential Store A CredentialStore object needs to be passed when creating the controllers. The CredentialStore can either load keys from a file through the function loadfromfile or from a string through load. $credentialstore = new CredentialStore(); $credentialstore->loadfromfile('/path/to/file'); $credentialstore->load('secret public'); Each line of the file/string must contain a secret key and a public key separated by an empty space. For example: 69b2048d-8bf8-4c1c-b49d-e a9a5 dce f ad28-0e1ab Account Linking In order to implement the Account Linking API using the SDK, use the controller class AccountLinkingController and pass a callback to ongetuserid. The callback receives a GetUserIdRequest object and returns a GetUserIdResponse. Example Code: $controller = new AccountLinkingController($credentialStore); $controller->ongetuserid(function ($req) { $id = $db->getid($req->getinfofield1(),$req->getinfofield2()); $res = new GetUserIdResponse(); if ($id) { $res->setresponse(getuseridresponsevalue::ok); $res->setuserid($id); else { $res->setresponse(getuseridresponsevalue::fail_account_invalid); return $res; ); $response = $controller->process($_server); echo $response; 26

27 Purchase Controller In order to implement the Purchase API using the SDK, use the controller class PurchaseController and implement callbacks to two operations onsubscriptionactivate and onsubscriptiondeactivate. SubscriptionActivate This callback receives a SubscriptionActivateRequest object and returns a SubscriptionActivateResponse object. SubscriptionDeactivate This callback receives a SubscriptionDeactivateRequest object and returns a SubscriptionDeactivateResponse object. Example code: $controller = new PurchaseController($credentialStore); $controller->onsubscriptionactivate(function ($req) { $res = new SubscriptionActivateResponse(); $res->setresponse(subscriptionactivateresponsevalue::ok); return $res; ); $controller->onsubscriptiondeactivate(function ($req) { $res = new SubscriptionDeactivateResponse(); $res->setresponse(subscriptiondeactivateresponsevalue::ok); return $res; ); $response = $controller->process($_server); echo $response; RUBY SDK The Ruby SDK is slightly different from other SDKs. The SDK is a simple library for request authorization only No controller code is provided to avoid restriction to a specific web framework The SDK can be found on GitHub Example code for Ruby on Rails: require 'amazon-instant-access' class VendorFulfillmentController < ApplicationController def create credentials = {'public_key' => 'secret_key' auth = AmazonInstantAccess::Authentication.new(credentials) auth.verify_request(request.method, request.url, request.raw_post, request.headers) operation = params['operation'] if operation == 'SubscriptionActivate' # Vendor logic elsif operation == 'SubscriptionDeactivate' # Vendor logic end render json: {response: 'OK', status: :ok end end Please refer to the README on the GitHub page for more information on how to use the SDK. 27

28 6. CUSTOMER EXPERIENCE This section describes how the digital purchase experience looks like to Amazon customers once we complete the integration process. EXAMPLE CUSTOMER FLOW SINGLE USER SUBSCRIPTIONS (SUS) 1. A customer locates an SUS product on the Amazon website through search, product recommendation, or a direct product link. The customer selects the number of licenses to purchase and clicks Add to Cart : 2. The customer is redirected to the order review screen. The customer clicks Place your order : 28

29 3. The customer sees the success page and clicks Your Games and Software Library to view the new subscription: Note: It may take some time for the fulfillment operation to go through, and subscription may not be accessible right away. A notification is sent to the customer once it is ready to be used. 4. The customer is redirected to the Subscriptions page. The customer clicks Manage Licenses : 5. The customer is redirected to the Licenses page. The customer clicks Add to assign license to assign the license and initiate the account linking process: 29

30 5. The customer is presented with the account linking page. The customer links the subscription to a new third-party account by clicking Create new account and link, or to an existing account by filling in the information fields on the right-hand side and clicking Link existing account : 6. If the customer clicks Create new account and link, your registration page is displayed in a pop-up window. The customer either creates a new account or logs in with an existing one (only if your registration page supports logins) to link to the Amazon account: Once the form submission is complete, account linking and subscription activation calls are sent to your web service. 30

31 7. When the API calls succeed, the item is fulfilled and the customer is redirected back to Your Game and Software Library page. At this point the customer can return to the Licenses page to manage the license: If customer clicks Cancel license, a subscription deactivation call is queued up to be sent to your fulfillment endpoint in the next renewal cycle. The customer can also click Turn off auto-renewal to disable the subscription renewal. 31

32 EXAMPLE CUSTOMER FLOW TEAM SUBSCRIPTIONS 1. A customer locates a Team Subscription product on the Amazon website through search, product recommendation, or a direct product link. The customer selects the number of licenses to purchase and clicks Add to Cart : 2. The customer is redirected to the order review screen, and clicks Place your order : 32

33 3. The customer sees the success page and clicks Your Games and Software Library to view the new subscription: Note: It may take some time for the fulfillment operation to go through, and subscription may not be accessible right away. A notification is sent to the customer once it is ready to be used. 4. The customer is redirected to the Subscriptions section in Your Games and Software Library page. The customer clicks Setup Account to initiate the account linking process: Note: The Access Product button is disabled until the account linking is complete and the subscription is activated. 33

34 5. The customer is presented with the account linking page. The customer links the subscription to a new third -party account by clicking Create new account and link, or to an existing one by filling in the account information fields on the right-hand side and clicking Link existing account : 6. If the customer clicks Create new account and link, your registration page is displayed in a pop-up window. The customer either creates a new account or logs in to an existing one (only if your registration page supports logins) to link to the Amazon account: Once the form submission is complete, account linking and subscription activation calls are sent to your web service. 34

35 7. When the subscription activation succeeds, the item is fulfilled and the customer is redirected back to Your Game and Software Library page. At this point, the customer can click Access Product to visit your license management page, or clicking Add to buy additional licenses for the subscription: Once the customer specifies the license quantity and clicks Add licenses, a subscription update call is sent to your web service. The customer can click on the information icon to view the license details. At this point, a subscription retrieval (get) call is sent to your web service. The custom can click admin console to visit your license management page: 35

36 If the subscription retrieval (get) API call fails for any reason, we display an error message or cached values instead: The customer can click Cancel subscription (see previous screenshot) to deactivate the subscription, at which point a subscription deactivation call is queued up to be sent to your fulfillment endpoint in the next renewal cycle: Note: The customer can click Undo cancellation to undo the cancellation any time before the renewal takes place. 36

37 Lastly, the customer can click Turn off auto-renewal to disable subscription renewal: Note: Billing and rollovers are handled completely by Amazon, and no API calls are sent to your service. 37