Amazon Pay and Login with Amazon integration guide

Step 3: Add a button widget

The Amazon Pay and Login with Amazon product consists of the Amazon Pay and the Login with Amazon services, which are technically closely related and run on the same platform.

  • Login with Amazon allows your buyer to sign in to your website with their Amazon login credentials. For first-time visitors, you can create a user account based on the user data that you receive from Amazon Pay.
  • Amazon Pay is a checkout option that lets the buyer choose a shipping address and payment method that is stored in their Amazon user account.

Both Amazon Pay and Login with Amazon are initiated by clicking the Login with Amazon or the Amazon Pay buttons. The buttons are added to your website as described below. The code for both buttons is almost identical. There is just one parameter that determines the button label. Further, there is a scope parameter that can be defined, regardless of the button type, and it determines which services can be used after a successful login, such as getting buyer profile information or conducting a payment transaction.

Note that a user login has two different dimensions:

  1. There is the website login, that is either done with an existing or newly created account on your website via the usual registration process or via the Login with Amazon button.
  2. There is a login in terms of an authentication against Amazon Pay that opens a session during which you can issue API calls for the logged-in customer. This login can be but is not required to be coupled with a website login as described in the first version. Alternatively, it could also be part of a guest checkout on your site.

When the buyer successfully signs in to Amazon, as described in the second option above, an access token is returned. The access token is specific to your client, the buyer, and the combination of scope parameters that you specify in the button code. For more information about scope parameters, see Button widget parameters. You will need the access token to retrieve customer profile data. For more information, see Obtaining profile information.

The procedure below describes an asynchronous loading of the button widget, which allows a web page 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.

Though it is not recommended, you can load the button widget synchronously. For more information, see Synchronous loading of JavaScript.

  1. In the body of the page, place the LoginWithAmazon <div> element before the JavaScript that renders the button or widgets.
    <body>
      // In the body of the page:
      <div id="LoginWithAmazon"></div>
  2. Within <script> tags add an onAmazonLoginReady callback.
    Set your clientID in the onAmazonLoginReady callback.
    <script>
      window.onAmazonLoginReady = function() { 
        amazon.Login.setClientId('YOUR-CLIENT-ID'); 
      };
    </script>
  3. Within the same script tags as described in the previous step, define a window.onAmazonPaymentsReady function and put the code for rendering the button into this function. The code below shows the full <script> section, including the code from the previous step.
    <script>
      window.onAmazonLoginReady = function() { 
        amazon.Login.setClientId('YOUR-CLIENT-ID'); 
      };
      
      window.onAmazonPaymentsReady = function(){
        // render the button here
        var authRequest; 
    
        OffAmazonPayments.Button('LoginWithAmazon', 'YOUR-SELLER-ID', {
          type:  "TYPE_PARAMETER", 
          color: "COLOR_PARAMETER", 
          size:  "SIZE_PARAMETER", 
          language: "ENTER_LANGUAGE_PARAMETER",
    
          authorization: function() { 
            loginOptions = {scope: "SCOPES", popup: "POPUP_PARAMETER"}; 
            authRequest = amazon.Login.authorize (loginOptions, "REDIRECT_URL"); 
          } 
        });
      }
    </script>

    The code sample above shows parameters that you can replace with your own values. For detailed information on the allowed values, see Button widget parameters below.

  4. Add error handling to the button code.
    . . .
    onError: function(error) { 
      // your error handling code.
      // alert("The following error occurred: " 
      //   + error.getErrorCode() 
      //   + ' - ' + error.getErrorMessage());
    } 
    . . .

    For more information about the onError handler, see Handling errors from Amazon Pay widgets or Testing your integration in the Sandbox environment.

  5. Add the Widgets.js script tag, as shown below, to your page. Make sure that it appears in the right order in your page code, which is after the script-tag that sets the client ID and renders the button (see the complete code sample below).
    <script async="async" type='text/javascript' 
        src='https://static-eu.payments-amazon.com/OffAmazonPayments/gbp/sandbox/lpa/js/Widgets.js'>
      </script>
  6. Add a logout option.
    <script>
      document.getElementById('Logout').onclick = function() {
        amazon.Login.logout();
      };
    </script>
    The logout option, often set up as a link, should delete any cached tokens and remove the user's profile information, like their name, from your website. Then your website can present the login button again. Call the amazon.Login.logout() method to delete any cached tokens and clear the session created by Amazon. Subsequent calls to amazon.Login.authorize present the login screen by default.

Button widget parameters

The following sections describe the parameters and their values contained in the JavaScript button widget code:

Your client ID

Replace YOUR_CLIENT_ID with your own client ID, which you received when setting up your Login with Amazon account. If you are not sure what your client ID is, sign in to Seller Central, and then go to Integration > MWS Access Key under Login with Amazon Account Information, Client ID.

Your seller ID

Replace YOUR_SELLER_ID with your own seller ID, which you received during registration. If you are not sure what your seller ID is, sign in to Seller Central, and then go to Integration > MWS Access Key under General Information, Seller ID.

Type

The type parameter is an optional parameter for indicating the type of button image that you want to select for your web page. Note that if you decide not to specify a value for type, the LwA (Login with Amazon) button will be set as the default value.

The following table shows the valid type parameter values, button descriptions, and sample button images.

Type codes

Button description

Button example

LwA

Specifies the Login with Amazon button.

This is the default button if type is not specified.

Login

Specifies the Login button.

PwA

Specifies the Amazon Pay button.

Pay

Specifies the Pay button.

A

Specifies the button that contains only the Amazon Pay logo.

Color

The color parameter is an optional parameter for choosing a button color. The following table shows the valid color code values, color descriptions, and color samples.

Color codes

Color description

Color example

Gold

Gold (default)

LightGray

Light gray

DarkGray

Dark gray

Size

The size parameter is an optional parameter for selecting a button size. Valid size code values are:

Regular

Retina

  • small
  • medium (default)
  • large
  • x-large

The actual size rendered depends on the type of button selected:

Parameter

type

LwA — Specifies the Login with Amazon button.

Login — Specifies the Login button.

A — Specifies the button that contains only the Amazon Pay logo.

size

  • small (156px x 32px)
  • medium (174px x 46px)
  • large (312px x 64px)
  • x-large (390px x 92px)
  • small (76px x 32px)
  • medium (101px x 46px)
  • large (152px x 64px)
  • x-large (202px x 92px)
  • small (32px x 32px)
  • medium (46px x 46px)
  • large (64px x 64px)
  • x-large (92px x 92px)


Parameter

type

PwA — Specifies the Amazon Pay button.

Pay — Specifies the Pay button.

A — Specifies the button that contains only the Amazon Pay logo.

size

  • small (148px x 30px)
  • medium (200px x 45px)
  • large (296px x 60px)
  • x-large (400px x 90px)
  • small (72px x 30px)
  • medium (90px x 45px)
  • large (144px x 60px)
  • x-large (180px x 90px)
  • small (32px x 32px)
  • medium (46px x 46px)
  • large (64px x 64px)
  • x-large (92px x 92px)

Language

The language parameter is an optional parameter for associating a language with an Amazon Pay or a Login with Amazon button. This is useful for offering multi-language support for an Amazon Pay and Login with Amazon experience for buyers on your website.

For example, a French-speaking buyer wants to make a purchase from a German website. The buyer, either by changing the language preference settings in their browser or by choosing from a language switcher on your website, can view Amazon Pay components in French.

The following table shows the valid language parameter values.

Language values

Language description

en-GB English (UK)
de-DE German (Germany)
fr-FR French (France)
it-IT Italian (Italy)
es-ES Spanish (Spain)

If you pass a language other than those listed above or no language parameter at all, the language defaults to the buyer's browser language. If the buyer's browser language preference setting is not one of the languages listed above, the language defaults to English. We recommend that you set the button language according to the language currently shown on your website. If your website allows language switching, the language of the Amazon Pay buttons should also be set to switch.

For more information, see Multi-language integration.

Pay button size examples

Scope

The value of the parameter scope that you choose influences both the content returned in the response of the call and the type of consent screen that Amazon Pay shows to the buyer to secure their permission for sharing their information.

You can use a combination of the following scope parameters:

Scope parameter

Description

Requirements

profile

Gives access to the full user profile (username, email address, and userID) after login.

--

profile:user_id

Gives access only to the userID from the user profile after login.

--

payments:widget

Required to show the Amazon Pay widgets (address and wallet widget) on your page. If used without the two parameters below, it gives access to the full shipping address after ConfirmOrderReference call and to the full billing address after successful authorization.

 

payments:shipping_address

Gives access to the full shipping address via the GetOrderReferenceDetails API call as soon as an address has been chosen in the address widget.

  • Requires scope parameter payments:widget
  • AddressConsentToken (=AccessToken) set in GetOrderReferenceDetails call.

payments:billing_address

Gives access to the full billing address via the GetOrderReferenceDetails API-Call as soon as a payment method has been chosen in the wallet widget.

  • Requires scope parameter payments:widget
  • accepted VAT agreement in Seller Central + VAT number provided
  • AddressConsentToken (=AccessToken) set in GetOrderReferenceDetails call.

Example: scope: profile payments:widget payments:shipping_address payments:billing_address

The payments:shipping_address provides access to the buyer's shipping address. To retrieve the full shipping address you need to call the getOrderReferenceDetails API. For more information, see "Getting the Shipping Address from Amazon" in Step 4: Add the AddressBook and Wallet Widgets, or GetOrderReferenceDetails in the Amazon Pay API reference guide.

Popup

The popup parameter determines whether the buyer is presented with a pop-up window to authenticate or if the buyer instead is redirected to an Amazon Pay page to authenticate.

Use one of the following popup parameters:

  • true — An Amazon Pay authentication screen is presented in a pop-up dialog where buyers can authenticate without ever leaving your website.

    This value is recommended for desktops where the button widget is presented on a secure page. Note that this option requires the button to reside on an HTTPS page with a valid TLS/SSL certificate.

  • false — The buyer is redirected to an Amazon Pay page within the same browser window.

    This value is recommended for smartphone-optimized devices or if you are rendering the button widget on a non-secure page. Note that the redirect URL must use HTTPS protocol and have a valid TLS/SSL certificate.

    For more information, see Enabling a redirect authentication.

Default: popup: true

When you embed an Amazon Pay button with the pop-up parameter set to true, the buyer will be asked for their Amazon Pay account email address and password:

As you can see in the previous screenshot, you can add your company logo to the authentication window. You can do this on Seller Central by clicking the Integration Settings link under Settings.

Redirect URL

The redirect URL is a parameter that determines the page that the buyer is redirected to after successfully authenticating. For example, after a successful authentication, you might want to take the buyer to the next page in your checkout pipeline to collect their shipping address and/or payment method details. Be aware that if you use popup:false in your button code, which means that you use the redirect login experience, you have to whitelist all of the redirect URLs in Seller Central in the Login with Amazon settings for your application.

Complete code sample


<body>
  // Add to the body of the page:
  <div id="LoginWithAmazon"> </div>  
  
  <script>
    window.onAmazonLoginReady = function() { 
      amazon.Login.setClientId('YOUR-CLIENT-ID'); 
    };
    
    window.onAmazonPaymentsReady = function(){
      // render the button here
      var authRequest; 
      
      OffAmazonPayments.Button("LoginWithAmazon", "YOUR-SELLER-ID", { 
        type:  "TYPE_PARAMETER", 
        color: "COLOR_PARAMETER", 
        size:  "SIZE_PARAMETER", 
        language: "LANGUAGE_PARAMETER",

        authorization: function() { 
          loginOptions = {scope: "SCOPES", popup: "POPUP_PARAMETER"}; 
          authRequest = amazon.Login.authorize (loginOptions, "REDIRECT_URL"); 
        }, 

        onError: function(error) { 
          // your error handling code.
          // alert("The following error occurred: " 
          //        + error.getErrorCode() 
          //        + ' - ' + error.getErrorMessage());
        } 
      });
    }
  </script>
 
  <script async="async" type='text/javascript' 
      src='https://static-eu.payments-amazon.com/OffAmazonPayments/gbp/
     sandbox/lpa/js/Widgets.js'>
  </script>

  . . .
   
  <script type="text/javascript">
    document.getElementById('Logout').onclick = function() {
      amazon.Login.logout();
    };
  </script>
</body>

The example above is for the sandbox environment. When you move your code to production, be sure to change the URL accordingly.

Notes

  • The corresponding div elements have to be placed before the JavaScript to render the buttons or widgets. The buttons and widgets are rendered in the onAmazonPaymentsReady callback, which is called after the widgets.js has been loaded.
  • Loading the widgets.js should occur only once, and it needs the async attribute in the <script> tag where the widgets.js is loaded.

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

Alternate scenarios:


Copyright © 2009-2017 Amazon.com, Inc. or its affiliates. Amazon and Amazon.com are registered trademarks of Amazon.com, Inc. or its affiliates. All other trademarks are the property of their respective owners.