Prerequisites

This guide demonstrates how to integrate with Amazon Pay and Login with Amazon in a test environment. This test environment, the Amazon Pay Sandbox view, lets you conduct an end-to-end test of your integration before going live. After a successful test, you can switch to the Production environment.

For more information, see Testing your integration with the Sandbox environment.

Configure your website for Amazon Pay

Amazon Pay and Login with Amazon work together to provide a great customer experience. Regardless of which button option you choose to use (Login with Amazon or Amazon Pay), you need to perform some base configurations for Amazon Pay. You can access the Amazon Pay configuration settings by going to Seller Central and clicking Integration Central under the Integration menu item.

  1. Login to Seller Central and select Integration > Integration Central from the navigation bar on the top-left side
  2. Under the Manage client ID/store ID(s) section, click on Create new client ID/store ID
  3. In the application details, add basic details about your website. These details are used on your website and mobile apps (if applicable).
    1. Application or store name:  This is the name that appears on the consent screen when the users agree to share their information with your website. This name applies to Android, iOS, and website versions of your application.
    2. Description:  A description of your website for Login with Amazon users.
    3. Privacy Notice URL:  The Privacy URL is the location of your company privacy policy. It also appears on the consent screen. This link is shown to users when they first sign in to your application (for example, http://www.example.com/privacy.html).
    4. Upload a logo:  This logo is shown on the sign-in and consent screens when customers sign in to your website or mobile app. The logo automatically resizes to 50 x 150 pixels. The following formats are accepted: PNG, JPEG, or GIF.
  4. Enter your Allowed JavaScript Origins and Allowed Return URLs to your application.
    Note: To use Amazon Pay or Login with Amazon with a website, you must specify an Allowed JavaScript origin (for the customer pop-up login experience). If you are implementing the redirect flow, you must also specify Allowed Return URLs.
    1. An origin is the combination of protocol, domain name, and port (for example, https://www.example.com:8443). Allowed origins must use the HTTPS protocol. If you are using a standard port (port 443), you need only include the domain name (for example, https://www.example.com). Adding your domain here allows the SDK for JavaScript to communicate with your website directly during the login process. Web browsers normally block cross-origin communication between scripts unless the script specifically allows it. To add more than one origin, click Add Another.
    2. If your website will be making HTTPS calls to the Amazon Pay authorization service and specifying a redirect_uri for replies, add those redirect URIs to Allowed Return URLs. The return URL includes the protocol, domain, path, and query string(s) (for example, https://www.example.com/login.php). To add more than one return URL, click Add Another.
  5. Click Save changes when done
  6. You are automatically assigned values for Client ID and Client Secret. The Client ID identifies your application, and the Client Secret is used in some circumstances to verify that your application is authentic. The Client Secret, like a password, is confidential. To see the Client Secret, click Show Secret.

Preparing to use the Amazon Pay and Login with Amazon widgets

To properly render the embedded widgets on your site, you must provide a handler for the onAmazonLoginReady callback and add a reference to the Amazon Pay and Login with Amazon JavaScript file, Widgets.js, to the source code for your webpage. You must do this from any webpage where you want to render Amazon Pay and Login with Amazon widgets.

To define onAmazonLoginReady callback and add a reference to the Amazon Pay and Login with Amazon JavaScript file, add a few lines of code as shown in the following sample code.

As a best practice, Amazon Pay recommends placing this code in the head section of your webpages that contain button, address, and wallet widgets. You also should not make a local copy or modify the content of the Amazon-provided JavaScript. Doing so can cause unintended consequences, like errors in the rendering or functionality of the widgets.

 
<head>
// your head section here
<script type='text/javascript'>
  window.onAmazonLoginReady = function() {
    amazon.Login.setClientId('YOUR_CLIENT_ID');
  };
</script>

<script type='text/javascript'
  src='https://static-eu.payments-amazon.com/OffAmazonPayments/eur/sandbox/lpa/js/
    Widgets.js'>
</script>
// your head section here
</head>

After the reference to the Amazon Pay and Login with Amazon JavaScript file has been added to your source code, you are ready to start embedding the Amazon Pay and Login with Amazon widgets.

Best practices

Encode your data before processing

We recommend that you encode any data that you receive from us before outputting it in any form, including HTML, JavaScript, or in a URL. Output encoding ensures that malicious scripts or any other injected executable cannot be executed on your website.

ESAPI, the Open Web Application Security Project (OWASP) API, provides a free, open source web application security control library that makes it easier to write lower-risk applications. Use this standard library to encode your output.

The following examples show how to encode data for some of the most common types of output:

  • HTML: String safe = ESAPI.encoder().encodeForHTML( request.getParameter( "input" ) );
  • HTML attributes values such as width, name or value: String safe = ESAPI.encoder().encodeForHTMLAttribute( request.getParameter( "input" ) );
  • URL Parameter values: String safe = ESAPI.encoder().encodeForURL( request.getParameter( "input" ) );
  • JavaScript data values: String safe = ESAPI.encoder().encodeForJavaScript( request.getParameter( "input" ) );

Asynchronous JavaScript

Amazon Pay has limited support for asynchronous loading of JavaScripts to render webpages more quickly. If you choose to use asynchronous loading, the only method Amazon Pay supports is an async attribute in a script tag.

Load the Amazon Pay button asynchronously

  1. In the header of the page, set your clientId in the onAmazonLoginReady callback.
  2. In the body of the page, place the "LoginWithAmazon" div element before the JavaScript that renders the button or widgets.
  3. Define a window.onAmazonPaymentsReady function. Move any JavaScript references to OffAmazonPayments into this function.
  4. Add the Widgets.js script tag, with the async attribute, below this definition.

To prevent timing issues, the script tags need to be positioned in the order listed above.

Here's an example:

 
// In the head of the webpage:
<head>
  <script type='text/javascript'>
    window.onAmazonLoginReady = function() {
      amazon.Login.setClientId('YOUR-CLIENT-ID');
    };
  </script>
</head>

// In the body of the page:
<div id="LoginWithAmazon"></div>

<script>
  window.onAmazonPaymentsReady = function(){
    // render the button here
    OffAmazonPayments.Button('LoginWithAmazon',
                         '<Your-Seller-ID>', {
      ...
  }
</script>

<script async='async' type='text/javascript' src=' https://static-eu.paymentsamazon.
com/OffAmazonPayments/eur/sandbox/lpa/js/Widgets.js'>
</script>

Note: The example above is for the Sandbox. When moving your code to Production, be sure to change the URL accordingly.

For more information about the script tag async attribute, see the Mozilla Developer Network script tag Summary.

See also