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.

  • Amazon Pay is a checkout option that lets the buyers choose a shipping address and payment method that is stored in their Amazon user account.
  • Login with Amazon lets your buyer sign in 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.

Both Amazon Pay and Login with Amazon are initiated by clicking the Amazon Pay or the Login with Amazon button. The buttons are added to your website as described below. The code for both buttons is almost identical. Just one parameter determines the button label. Furthermore, you can define a scope parameter, regardless of the button type, and it determines which services can be used after a successful login, like 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 will open a session during which you can issue API calls for the signed-in customer. This login can be but is not required to be coupled with a website login as described in the first dimension. 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 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.
     
    <!-- 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('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('CLIENT-ID'); 
      };
    
      window.onAmazonPaymentsReady = function(){
        // render the button here
        var authRequest; 
    
        OffAmazonPayments.Button('LoginWithAmazon', 'SELLER-ID', {
          type:  'TYPE', 
          color: 'COLOR', 
          size:  'SIZE', 
          language: 'LANGUAGE',
    
          authorization: function() { 
            loginOptions = {scope: 'SCOPES', popup: POPUP}; 
            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.
      console.log("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 to the before the closing body tag to end of your page as shown below. 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" 
      src='https://static-eu.payments-amazon.com/OffAmazonPayments/eur/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.
  7. Add a tooltip with informational text.
    Amazon Pay recommends adding a tooltip, with a "?" icon, to the right side of button widget. If you have limited space, implement the tooltip so that it is shown when the buyer hovers over the button widget.

    Recommended informational text per language:
    • EN: "Amazon Pay uses the addresses and payment methods stored in your Amazon account for fast, secure checkout."
    • DE: "Amazon Pay verwendet die in Ihrem Amazon-Konto gespeicherten Zahlungs- und Versandinformationen."
    • FR: "Amazon Pay utilise les informations de paiement et de livraison enregistrees sur votre compte Amazon."
    • IT: "Amazon Pay utilizza le informazioni di pagamento e consegna memorizzate nel tuo account Amazon."
    • ES: "Amazon Pay utiliza la informacion de pago y entrega almacenada en tu cuenta de Amazon."

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 choose for your web page. Note that if you decide not to specify a value for type, the LwA (Login with Amazon) button is 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.
PwA Specifies the Amazon Pay button.

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 choosing 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 you choose:

Parameter
type LwA - Specifies the Login with Amazon button. PwA - Specifies the Amazon Pay button.
size
  • small (156px x 32px)
  • medium (195px x 46px)
  • large (312px x 64px)
  • x-large (390px x 92px)
  • small (148px x 30px)
  • medium (200px x 45px)
  • large (296px x 60px)
  • x-large (400px x 90px)

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 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 making a selection 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 Buttons
de-DE Germany's German
en-GB UK English
es-ES Spain's Spanish
fr-FR France's French
it-IT Italy's Italian

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.

Buttons are available for languages supported by Amazon Pay.

For more information, see Multi-language integration.

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 selected in the address widget.
  • Requires scope parameter payments:widget
  • 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 selected in the wallet widget.
  • Requires scope parameter payments:widget
  • 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.

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

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. Be aware 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. Be aware 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 is 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 which page 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 add all the redirect URLs to an access list in Seller Central. Instructions for adding the redirect URLs to the access list can be found here: Adding allowed JavaScript origins or allowed return URLs

Complete code sample

 
<body>
  // Add to the body of the page:
  <div id="LoginWithAmazon"> </div>  
  
  <!-- . . . -->
  
  <p id="Logout">logout</p>


  <script>
    window.onAmazonLoginReady = function() { 
    amazon.Login.setClientId('CLIENT-ID'); 
  };
    
    window.onAmazonPaymentsReady = function(){
      // render the button here
      var authRequest; 
	
      OffAmazonPayments.Button('LoginWithAmazon', 'SELLER-ID', {
	    type:  'TYPE', 
	    color: 'COLOR_PARAMETER', 
	    size:  'SIZE_PARAMETER', 
	    language: 'LANGUAGE_PARAMETER',
	
	    authorization: function() { 
	      loginOptions = {scope: 'SCOPES', popup: POPUP_PARAMETER}; 
	      authRequest = amazon.Login.authorize (loginOptions, 'REDIRECT_URL'); 
	    } 
      });
	}
  </script>
 
  <!-- . . . -->
   
  <script 
    document.getElementById('Logout').onclick = function() {
      amazon.Login.logout();
    };
  </script>

  <script async="async" 
    src='https://static-eu.payments-amazon.com/OffAmazonPayments/eur/sandbox/lpa/js/Widgets.js'>
  </script>

</body>
    

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

Note:

  • 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.

See also