Thank you for your visit. This page is only available in English at this time.
 Prerequisites | Amazon Pay

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 in the Sandbox environment.

Configure your website for Amazon Pay and Login with Amazon

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 of Login with Amazon. You access the Login with Amazon configuration settings from the Login with Amazon Seller Central page.

  1. On the Login with Amazon Seller Central page, register a new application by clicking the Register new Application button.
  2. In the application details page, add basic details about your website. These details are used on your website and mobile apps (if applicable).
    1. Name Shown to Users  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. Logo Image File  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.
  3. When you are finished, click Save.

Add a website to your application

  1. From the Application screen, click Web Settings  You are automatically assigned values for Client ID and Client Secret. The Client ID identifies your website, and the Client Secret is used in some circumstances to verify that your website is authentic. The Client Secret, like a password, is confidential. To see the Client Secret, click Show Secret.
  2. To add Allowed JavaScript Origins or Allowed Return URLs to your application, click Edit. Note: To use Login with Amazon with a website, you must specify either an Allowed JavaScript origin (for the customer pop-up login experience) or an Allowed Return URL (for the customer redirect login screen experience). If you are using Amazon Pay, you must specify one of the options.
  3. 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.
  4. If your website will be making HTTPS calls to the Login with Amazon 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. To finish configuring Login with Amazon, click Save.

Getting ready 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 example 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 async='async' type='text/javascript'
  src='https://static-na.payments-amazon.com/OffAmazonPayments/us/sandbox/js/
    Widgets.js'>
</script>
// your head section here
</head>
    

The script tag in the sample above contains an async attribute that allows the webpage to load more quickly while the JavaScript code required by Amazon Pay is loaded in the background. This is the only asynchronous method supported by Amazon Pay.

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, like 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 provides 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.

To 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 web page:
<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-na.payments-amazon.
com/OffAmazonPayments/us/sandbox/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