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 AddressBook and Wallet widgets on your site. The AddressBook and Wallet widgets show the addresses and payment instruments for the logged in customer, as they are provided in the corresponding Amazon account. One of these addresses and payment instruments are pre-selected when the widgets are rendered automatically.

Figure 1: The AddressBook widget shows the addresses stored in a buyer’s Amazon account
Figure 2: The Wallet widget displays the payment methods stored in a buyer’s Amazon account

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

Embedding the widgets

  1. Like on any page where you use Amazon Payments 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/eur/sandbox/lpa/js/Widgets.js'>
    </script>
    		
    Figure 3: JavaScript Code enabling Login and Pay with Amazon

    For more details on these JavaScript blocks, check the section Add a button widget.

  2. Embed the widgets on your website by adding code to the HTML page where you want them to display. It makes a difference whether you include both widgets on one page or if you have distinct pages that render them. Therefore, there are different samples for one-page and multi-page checkouts. Which of the options you use in your shop is your decision. Using a one-page checkout allows to finish purchases quicker and with less clicks while multi-page is slightly easier to integrate.
    See the sample code below:

  3. 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 4: Meta Element to support responsive/mobile designs
  4. 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 example styles will make your widgets scale as much as possible. Don't reduce the min-width further than 280px — it will break the layout and will cause overlapping text inside of them. We recommend using a min-width of 300px.
  5. /* 
    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: 100%;
        max-width: 900px;
        min-height: 228px;
        height: 240px;
        max-height: 400px;
    }
    
    #walletWidgetDiv {
        min-width: 300px;
        width: 100%;
        max-width: 900px;
        min-height: 228px;
        height: 240px;
        max-height: 400px;
    }
    
    
    /* The following are required only when you use the read-only widgets: */
    
    #readOnlyAddressBookWidgetDiv {
        min-width: 266px;
        width: 100%;
        max-width: 900px;
        min-height: 145px;
        height: 165px;
        max-height: 180px;
    }
    
    #readOnlyWalletWidgetDiv {
        min-width: 266px;
        width: 100%;
        max-width: 900px;
        min-height: 145px;
        height: 165px;
        max-height: 180px;
    }	
    		
    Figure 5: CSS Sample for Responsive Designs

    In case you need to limit the space that the widgets require to the absolute minimum, consider using the collapsible widgets for smart phones. They will show only the pre-selected entry and a button to change the selection that will expand the widget to show the other addresses. Make sure that this expansion of the widgets will not break your page layout, and don't embed them in fixed height boxes.

Checkout Workflow

Note: On 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 do not influence the correct operation of all other elements. Also, implement a comprehensive logging, especially for the error and exception handling, to allow solving potential problems quickly and with manageable effort.

Short Overview

The following steps usually need to be performed on the page or the pages showing the widgets. If you are following one of the alternative integration scenarios, 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 respectively 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 become aware of any change inside the widgets. Unless the signed-in customer has no shipping addresses or payment instruments in his account, a shipping address and a payment instrument are pre-selected when you render the widgets. This pre-selection also triggers the onAddressSelect or onPaymentSelect event. That means you can use them to:

  1. identify changes to update the addresses by sending a GetOrderReferenceDetails API call
  2. make sure that a shipping address and a payment method is selected before you allow your customer to proceed with the checkout

Whether or not you need to do 1. depends on your integration. If you show shipping cost, delivery options (for example, express and standard), custom taxes, or anything else that depends on the selected 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 here and display 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 in consequence 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

How could that happen?
Amazon requires the payment method to be confirmed once when a new address is entered as part of the fraud prevention strategies. In consequence, the set of available payment instruments in the wallet widget might vary for different shipping address. In order to show the right set of payment methods, the wallet widget is automatically invalidated and re-rendered on any selection change in the address widget. As a result, the wallet widget might become empty after selection of a different shipping address.

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

  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, you must also make sure that there are no constraints 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 Pay 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. In order to be able to do that, it is required that you submit the preliminary order total after the shipping address was selected and before the wallet widget is rendered. Since 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 made the setOrderReferenceDetails API call by means of executing its JavaScript code again. For details, see 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 on 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.

AddressBook Widget in Multipage Checkout

<!-- Place this code in your HTML where you want 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/eur/sandbox/lpa/js/Widgets.js'>
</script>
	
Figure 6: 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/eur/sandbox/lpa/js/Widgets.js'>
</script>
Figure 7: JavaScript code to add the wallet widget in a multipage checkout

Address and Wallet Widget on Same Page

In case of a one-page checkout or any other kind of 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 usually will not have an Order-Reference-Id yet when the widget is loaded, since the ID is created in the addressbook widget by default. As a consequence, the parameter amazonOrderReferenceId cannot be provided in the wallet widget code, and it doesn't need to be because it can take the OrderReferenceId from the session. If you decide to do a synchronous authorization later (see Request an Authorization), you must change the widget code of both AddressBook and Wallet widget in order to use a specified amazonOrderReferenceId instead of generating a new one. More details on this topic will ge provided later during your integration in the step handling payment declines.

<!-- 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',
	scope: 'SCOPE',
    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/eur/sandbox/lpa/js/Widgets.js'>
</script>
Figure 8: JavaScript code to add both widgets on the same page

Additional Information


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.