Amazon Pay and Login with Amazon integration guide

Step 4: Add the AddressBook and Wallet widgets

After a buyer is successfully authenticated, you can render the Amazon Pay and Login with Amazon AddressBook and Wallet widgets on your site. The AddressBook and Wallet widgets show the addresses and payment instruments for the signed-in customer, as they are provided in the corresponding Amazon account. One of these addresses and payment instruments will be pre-selected when the widgets are rendered automatically.

You can use the widgets in sandbox mode without limitations, but they will not work in production (live mode) until you finish the account registration completely, which includes the validation process that you need to complete when you have access to Seller Central.

Embedding the widgets

As on any page where you use Amazon Pay functions, you must include the JavaScript blocks that load the widgets.js and set the Client-ID. Make sure that they appear in your code in the same order as shown in figure 1. There can be other code between the two script blocks.



<script>
  window.onAmazonLoginReady = function() { 
    amazon.Login.setClientId('YOUR-CLIENT-ID'); 
  };
</script>

<script async="async" 
src='https://static-eu.payments-amazon.com/OffAmazonPayments/gbp/sandbox/lpa/js/Widgets.js'>
</script>
		
Figure 1: JavaScript Code enabling Login and Pay with Amazon

For more details about these JavaScript blocks, check the section Step 3: Add a button widget.


  1. Embed the widgets on your website by adding code to the HTML page where you want them to appear. Because it makes a difference whether you include both widgets on one page or if you have distinct pages that render them, there are different samples for one-page and multipage checkouts. Using a one-page checkout lets customers finish purchases quicker and with fewer clicks, while multipage checkout is slightly easier to integrate.
    See the sample code below:
  2. Add a <meta> tag to the head of your web page for mobile-optimized websites. The <meta> tag scales the widgets to the size of the screen so that it is readable on a mobile device or e-reader without requiring the user to manually zoom the page.
    <meta name="viewport" content="width-device-width,initial-scale=1.0, maximum-scale=1.0"/>
    		
    Figure 2: Meta Element to support responsive/mobile designs
  3. Specify the width and height parameters so that the widgets will render. We assume that you do this in CSS style documents rather that doing it inline. The following sample styles will make your widgets scale as much as possible. Do not reduce the min-width further than 280px because it will break the layout and will cause overlapping texts inside of them. It is recommenced to use a min-width of 300px.
  4. /* 
    Please include the min-width, max-width, min-height 
    and max-height if you plan to use a relative CSS unit 
    measurement to make sure the widget renders in the 
    optimal size allowed.    
    */
    
    #addressBookWidgetDiv {
      min-width: 300px; 
      width: 600px;  /*width can be removed and the widget will take up all the page width*/
      max-width: 100%;
      min-height: 228px; 
      height: 240px;
    }
    #walletWidgetDiv {
      min-width: 300px; 
      width: 600px;  /*width can be removed and the widget will take up all the page width*/
      max-width: 100%;
      min-height: 228px; 
      height: 240px;
    }
    			
    /* The following are only required when you use the read-only widgets: */
    #readOnlyAddressBookWidgetDiv {
      min-width: 266px; 
      max-width:100%; 
      height: 165px;
    }
    #readOnlyWalletWidgetDiv {
      min-width: 266px; 
      max-width: 100%; 
      height: 165px;
    }
    		
    Figure 3: CSS Sample for Responsive Designs

Checkout workflow

In every step that is explained here, always keep in mind that errors can occur, no matter how rarely this might happen. Be sure to write your code in a way that errors in one functionality, like the Amazon Pay integration, do not influence the correct operation of all other elements. Also, implement comprehensive logging, especially for the error and exception handling, to allow solving potential problems quickly and with minimal effort.

Short overview

The following steps must usually be performed on the page or pages that show the widgets. If you follow one of the alternative integration scenarios, however, the steps might be slightly different.

  1. Make sure that you received and stored the AccessToken
  2. Render the AddressBook widget.
  3. Get the Shipping address with getOrderReferenceDetails API call.
  4. Check whether the destination is supported by the shop configuration.
  5. Determine delivery options and costs according to the destination.
  6. Submit preliminary order total by setOrderReferenceDetails API call.
  7. (Re-)render the wallet widget after the setOrderReferenceDetails call.
  8. Get the billing address with getOrderReferenceDetails API call.
  9. Check the OrderReferenceDetails for constraints.

Get shipping and billing address

You can get the shipping and billing addresses in the checkout as soon as an address in the wallet widget or a payment method in the wallet widget is selected.

Requirements:

  • Scope parameter payments:shipping_address for the full shipping address
  • Scope parameter payments:billing_address for the billing address
  • Parameter AddressConsentToken set to the AccessToken in GetOrderReferenceDetails call

You can and should use the onAddressSelect and onPaymentSelect callbacks in the widgets to get aware of any change inside the widgets. Unless the signed-in customer doesn't have any shipping addresses or payment instruments in his account, a shipping address and a payment instrument will be pre-selected when you render the widgets. This pre-selection will also trigger the onAddressSelect or onPaymentSelect event. That means you can use them to:

  • Become aware of changes to update the addresses by sending a GetOrderReferenceDetails API call.
  • Make sure that a shipping address and a payment method is selected before you allow your customer to proceed to checkout.
  • Whether or not you need to do 1. depends on your integration. If you show shipping cost, delivery options (like express and standard), custom taxes, or anything else that depends on shipping address on the same page with the AddressBook widget, then you will probably need to request the new address at any change in the widgets. In case you just show the widget and anything else depending on their selection on the next page in your checkout flow, doing that once before the next page is loaded is sufficient.

    Point 2. is important because in rare cases it might happen that the widgets are empty and thus no entry can be automatically selected. This can happen in the following cases:

    For the address widget:

    • No address was ever entered in the Amazon customer account.

    For the wallet widget:

    • No payment instrument was ever provided for this account.
    • No payment instrument was ever confirmed for the selected shipping address.

    The background of the latter is that Amazon requires the payment method to be confirmed once when a new address is entered as part of the fraud protection. Consequently, the set of available payment instruments in the wallet widget depends on the selected shipping address. Therefore, any selection change in the address widget invalidates and re-renders the wallet widget, which can consequently appear empty sometimes.

    Proceeding to checkout without a valid selection in the widgets will result in errors when the order and, respectively, the payment are confirmed. Therefore, before you allow your customer to proceed to checkout make sure that:

    1. There was at least one onAddressSelect event.
    2. There was at least one onPaymentSelect event after the last onAddressSelect event.

    Before proceeding to the next step in the checkout, also make sure that no constraints are on the OrderReferenceObject. For more information, see the Order Reference Constraints section of the API Reference Guide.

    Submit preliminary order total

    Depending on the cart value, it might happen that certain payment instruments available in an Amazon customer account cannot be used. In such cases, the corresponding payment instruments will be deactivated in the wallet widget in order to prevent their selection. To be able to do that, you must submit the preliminary order total after the shipping address was selected and before the wallet widget is rendered. Because this is usually not possible when both widgets are shown on the same page, make sure that you re-render the wallet widget after you make the setOrderReferenceDetails API call by means of executing its JavaScript code again. More details on this can be found in section Re-Rendering the wallet widget.

    If you don't do this, a payment method might be selected that will be excluded later when you submit the final order total at the time of order confirmation, resulting in a constraint in the OrderReferenceObject and also in an error for the ConfirmOrderReference API call. For more details, see the list of possible order reference constraints and the section on how to simulate them when testing your integration.

    Making a call to the GetOrderReferenceDetails API

    Making a call to the GetOrderReferenceDetails API

    						 https://mws.amazonservices.com/OffAmazonPayments_Sandbox/2013-01-01 ?AWSAccessKeyId=AKIAJKYFSJU7PEXAMPLE &Action=GetOrderReferenceDetails &AddressConsentToken=IQEBLzAtAhUAjagYW4Jrgw84pCaaIDjrKoEhZXsEXAMPLE &AmazonOrderReferenceId=S23-1234567-1234567 &SellerId=YOUR_SELLER_ID_HERE &SignatureMethod=HmacSHA256 &SignatureVersion=2 &Timestamp=2012-10-03T19:01:11Z &Version=2013-01-01 &Signature=CLZOdtJGjAo81IxaLoE7af6HqK0EXAMPLE 
    					

    AddressBook widget in multipage checkout

    <!-- Place this code in your HTML where you would like the address widget to appear. -->
    <div id="addressBookWidgetDiv"> </div> 
    
    <script>
    window.onAmazonLoginReady = function() {amazon.Login.setClientId('YOUR-CLIENT-ID'); };
    window.onAmazonPaymentsReady = function() {
    
      new OffAmazonPayments.Widgets.AddressBook({
        sellerId: 'YOUR_SELLER_ID_HERE',
        scope: 'SCOPE',
        onOrderReferenceCreate: function(orderReference) {
          // Here is where you can grab the Order Reference ID.
          orderReference.getAmazonOrderReferenceId();
        },
    	onAddressSelect: function(orderReference) {
          // Replace the following code with the action that you want
          // to perform after the address is selected. The 
          // amazonOrderReferenceId can be used to retrieve the address 
          // details by calling the GetOrderReferenceDetails operation. 
        },
        design: {
          designMode: 'responsive'
        },
        onReady: function(orderReference) {
          // Enter code here you want to be executed 
          // when the address widget has been rendered. 
        },
    
        onError: function(error) {
          // Your error handling code.
          // During development you can use the following
          // code to view error messages:
          // console.log(error.getErrorCode() + ': ' + error.getErrorMessage());
          // See "Handling Errors" for more information.
        }
      }).bind("addressBookWidgetDiv");
    };
    </script>
    
    <script async="async" 
    	src='https://static-eu.payments-amazon.com/OffAmazonPayments/gbp/sandbox/lpa/js/Widgets.js'>
    </script>
    	
    Figure 4: JavaScript code to add the AddressBook widget in a multipage checkout

    Wallet widget in multipage checkout

    The following code can be used for integrations where the address wallet widget appear on different pages in your checkout flow. In case you have both on the same page, use the code shown in the one-page checkout sample code.

    <!-- Place this code in your HTML where you want the wallet widget to appear. -->
    <div id="walletWidgetDiv"></div>
    
    <script>
    window.onAmazonLoginReady = function() {amazon.Login.setClientId('YOUR-CLIENT-ID'); };
    window.onAmazonPaymentsReady = function() {
      new OffAmazonPayments.Widgets.Wallet({
        sellerId: 'YOUR_SELLER_ID_HERE',
        scope: 'SCOPE',	
           amazonOrderReferenceId: 'ORDER_REFERENCE_ID', //the one you created before, most likely in the AddressBook widget
        onPaymentSelect: function(orderReference) {
          // Replace this code with the action that you want to perform
          // after the payment method is selected.
    
          // Ideally this would enable the next action for the buyer
          // including either a "Continue" or "Place Order" button.
        },
        design: {
          designMode: 'responsive'
        },
        onError: function(error) {
          // Your error handling code.
          // During development you can use the following
          // code to view error messages:
          // console.log(error.getErrorCode() + ': ' + error.getErrorMessage());
          // See "Handling Errors" for more information.
        }
      }).bind("walletWidgetDiv");
    };
    </script>
    
    <script async="async" 
    	src='https://static-eu.payments-amazon.com/OffAmazonPayments/gbp/sandbox/lpa/js/Widgets.js'>
    </script>
    
    Figure 5: JavaScript code to add the wallet widget in a multipage checkout

    AddressBook and Wallet widget on same page

    In case of a one-page checkout or any other kind in an integration where you present both widgets on the same page, you have to include their JavaScript code in the same onPaymentsReady function, as shown below in figure 6.

    Note:
    When showing both widgets on the same page, you will usually not have the Order-Reference-Id when the widget is loaded, since the ID is created in the AddressBook widget by default. Therefore, the parameter amazonOrderReferenceId is not provided in the wallet widget code. This will work since it can take the OrderReferenceId from the session. In case you should decide to do a synchronous authorization later (see Request an Authorization), you will have to change the widget code of both, AddressBook and Wallet widgets, in order to use a specified amazonOrderReferenceId instead of generating a new one. The integration guide section about handling payment declines addresses this in more detail.

    <!-- Place this code in your HTML where you would like the address widget to appear. -->
    <div id="addressBookWidgetDiv"> </div> 
    
    <!-- Place this code in your HTML where you would like the wallet widget to appear. -->
    <div id="walletWidgetDiv"> </div>
    
    <script>
    window.onAmazonLoginReady = function() {amazon.Login.setClientId('YOUR-CLIENT-ID'); };
    window.onAmazonPaymentsReady = function() {
      new OffAmazonPayments.Widgets.AddressBook({
        sellerId: 'YOUR_SELLER_ID_HERE',
        scope: 'SCOPE',
        onOrderReferenceCreate: function(orderReference) {
          // Here is where you can grab the Order Reference ID.
          orderReference.getAmazonOrderReferenceId();
        },
        onAddressSelect: function(orderReference) {
          // Replace the following code with the action that you want
          // to perform after the address is selected. The 
          // amazonOrderReferenceId can be used to retrieve the address 
          // details by calling the GetOrderReferenceDetails operation. 
    
          // If rendering the AddressBook and Wallet widgets
          // on the same page, you do not have to provide any additional
          // logic to load the Wallet widget after the AddressBook widget.
          // The Wallet widget will re-render itself on all subsequent 
          // onAddressSelect events, without any action from you. 
          // It is not recommended that you explicitly refresh it.
        },
        design: {
          designMode: 'responsive'
        },
        onReady: function(orderReference) {
          // Enter code here you want to be executed 
          // when the address widget has been rendered. 
        },
        onError: function(error) {
          // Your error handling code.
          // During development you can use the following
          // code to view error messages:
          // console.log(error.getErrorCode() + ': ' + error.getErrorMessage());
          // See "Handling Errors" for more information.
        }
      }).bind("addressBookWidgetDiv");
    
      new OffAmazonPayments.Widgets.Wallet({
        sellerId: 'YOUR_SELLER_ID_HERE',
        onPaymentSelect: function(orderReference) {
          // Replace this code with the action that you want to perform
          // after the payment method is selected.
    
          // Ideally this would enable the next action for the buyer
          // including either a "Continue" or "Place Order" button.
        },
        design: {
          designMode: 'responsive'
        },
        onError: function(error) {
          // Your error handling code.
          // During development you can use the following
          // code to view error messages:
          // console.log(error.getErrorCode() + ': ' + error.getErrorMessage());
          // See "Handling Errors" for more information.
        }
      }).bind("walletWidgetDiv");
    };
    </script>
    
    <script async="async" 
    	src='https://static-eu.payments-amazon.com/OffAmazonPayments/gbp/sandbox/lpa/js/Widgets.js'>
    </script>
    
    Figure 6: JavaScript code to add both widgets on the same page

    See also


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.