Step 2: Add the AddressBook and Wallet widgets

After a buyer has successfully authenticated, you can render the Amazon Pay AddressBook and Wallet widgets in the location of your choosing. The AddressBook and Wallet widgets show the shipping addresses and payment methods the buyer has saved in their Amazon account, respectively.

To embed the AddressBook widget on your website, add the following sample code to your webpage:

 
<!--- put the style below inside your CSS file -->
<style type="text/css">
   #addressBookWidgetDiv{width: 400px; height: 228px;}
</style>

<div id="addressBookWidgetDiv">
</div>

<script>
  new OffAmazonPayments.Widgets.AddressBook({
    sellerId: 'YOUR_SELLER_ID_HERE',
    agreementType: 'BillingAgreement',
     
    onReady: function(billingAgreement) {
      var billingAgreementId = billingAgreement.
      getAmazonBillingAgreementId(); 
    },
    onAddressSelect: function(billingAgreement) {
      // Replace the following code with the action that you want to perform
      // after the address is selected.
      // The amazonBillingAgreementId can be used to retrieve
      // the address details by calling the GetBillingAgreementDetails operation.
      // If rendering the AddressBook and Wallet widgets on the same page, you
      // should wait for this event before you render the Wallet widget for
      // the first time.
      // The Wallet widget will re-render itself on all subsequent
      // onAddressSelect events without any action from you. We don't
      // recommend that you explicitly refresh it.
    },
    design: {
      designMode: 'responsive'
    },
    onError: function(error) {
      // your error handling code
    }
  }).bind("addressBookWidgetDiv");
</script>
    

Note: If you specify the value of agreementType as billingAgreement, Amazon Pay creates a Billing Agreement object in the Draft state. The Draft Billing Agreement object is canceled if you do not complete Step 4: Set billing agreement details and confirm the agreement within three hours of a buyer clicking the button on your site.

Note: If you want to use Amazon Pay to enable only one-time purchases, assign the value of the agreementType parameter as orderReference. If you want to proceed with this path, see the Amazon Pay and Login with Amazon integration guide.

If you are using both the Amazon Pay AddressBook and Wallet widgets, you must specify the 'onReady' callback function as one of the parameters in the widget code. The 'onReady' function creates the Billing Agreement object when the widget renders. You can get the billingAgreementId by calling the getAmazonBillingAgreementId() function on the billingAgreement object.

Note: If you do not want to use the Amazon Pay AddressBook to collect addresses from the buyer, refer to Integrating without the AddressBook widget.

Embed the Wallet widget on your website

Add the following sample code to your webpage:

 
<!--- please put the style below inside your CSS file -->
<style type="text/css">
   #walletWidgetDiv{width: 400px; height: 228px;}
</style>

<div id="walletWidgetDiv">
</div>

<script>
  walletWidget = new OffAmazonPayments.Widgets.Wallet({
    sellerId: 'YOUR_SELLER_ID_HERE',
    // amazonBillingAgreementId obtained from the AddressBook widget
    amazonBillingAgreementId: amazonBillingAgreementId,
    onPaymentSelect: function(billingAgreement) {
      // Replace this code with the action that you want to perform
      // after the payment method is selected.
    },
    design: {
      designMode: 'responsive'
    },
    onError: function(error) {
      // your error handling code
    }
  });
  walletWidget.setPresentmentCurrency("GBP"); 
     // ISO-4217 currency code, merchant is expected to enter a valid currency supported by Amazon Pay.
  walletWidget.bind("walletWidgetDiv");
</script>
    

You can control the widget height and width in your CSS as long as you provide a height and width range within our allowed parameters. You can also use other CSS unit measurements, like percent, REM, and EM, as long as the minimum and maximum height and the width of the element are within the provided ranges.

If you have a responsive site, follow these steps:

1. Add a meta tag to the head section of each of your smartphone-optimized pages. This meta tag causes the widgets to scale to the size of the available screen so that it is readable on a smartphone without requiring the user to manually zoom the page:

   
   <meta name="viewport" content="width-device-width, initial-scale=1.0, maximum-scale=1.0"/>
   

2. You can use media query with a CSS to build a mobile first design with example below:

   
   <style type="text/css">
   
   
   /* 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 theoptimal size allowed. */
   
   #addressBookWidgetDiv {min-width: 300px; max-width: 600px; min-height:228px; max-height: 400px;}
   #walletWidgetDiv {min-width: 300px; max-width:600px; min-height: 228px; max-height: 400px;}
    
   /* Smartphone and small window */
   #addressBookWidgetDiv {width: 100%; height: 228px;}
   #walletWidgetDiv {width: 100%; height: 228px;}
    
   /* Desktop and tablet */
   @media only screen and (min-width: 768px) {
      #addressBookWidgetDiv {width: 400px; height: 228px;}
      #walletWidgetDiv {width: 400px; height: 228px;}
   }
       
   

When creating the AddressBook and Wallet widgets, you must specify width and height parameters; otherwise, the widgets don't render. The recommended and valid width and height parameters for the one- and two-column widgets are specified in the following table:

Following a successful authentication, the buyer sees the AddressBook widget where you specified the widget to render, similar to the following screenshot:

Note that in the previous screenshot, the AddressBook and Wallet widgets render directly on your website.

We recommend that you disable the checkout workflow until you are sure that the buyer has chosen an address and payment method from the respective widgets. Amazon Pay notifies you of the address and payment method selection through the onAddressSelect and onPaymentSelect callback functions, respectively. Based on these notifications, you can enable the next step in your checkout flow. For example, you can enable the Continue button on your webpage if you have an order review page that follows.

Notes

• If you render the AddressBook and Wallet widgets on the same page, listen to the onAddressSelect event before you render the Wallet widget for the first time.
• If you are using both the AddressBook and Wallet widgets, a buyer must choose both an address and a payment method before you can confirm the billing agreement. If the buyer changes their address choice after making an initial address and payment method choice, they must then reselect a payment method. This means that you must listen for an onPaymentSelect notification following each address selection (onAddressSelect notification). If you do not need to collect address information from the AddressBook widget, see Integrating without the AddressBook widget.

Getting the shipping address

In many cases, you need the buyer's shipping address to calculate shipping charges and taxes. After receiving the onAddressSelect notification, you can call the GetBillingAgreementDetails operation to retrieve the address the buyer has chosen. You can also provide your buyers with immediate feedback if they chose an unsupported address from the widget. In this situation, you should show a message to the buyer that they need to choose a different shipping address from the widget.

If you are using the Amazon Pay button (guest checkout), you have access to a partial shipping address (city, state, postal code, and country). To have access to the full shipping address, use the Amazon Pay button and set the payments:shipping_address scope parameter in the JavaScript you use to embed the button on your webpage. For more information about scope parameters, see the ENTER_SCOPES section in Step 1: Add a Button widget for buyer authentication.

In all cases, you receive the full shipping address from the GetBillingAgreementDetails operation after you have confirmed the billing agreement to Amazon Pay. For more information, see Step 4: Set billing agreement details and confirm the agreement.

To retrieve the address that the buyer has chosen, call the GetBillingAgreementDetails operation after the onAddressSelect notification has fired.

Note: All of your API calls must be signed for them to work properly. To sign your API requests, you need Amazon MWS keys. You can get these keys by signing into Seller Central, pointing to the Integration tab, and then clicking MWS Access Key. This Amazon MWS key must be set in the AWSAccessKeyId request parameter of the Amazon Pay API section operations. For more information about how to configure your services to make signed API calls, see the Amazon MWS Developer Guide.

The following example shows how to call the GetBillingAgreementDetails operation:

 
https://mws-eu.amazonservices.com/OffAmazonPayments_Sandbox/2013-01-01
?AWSAccessKeyId=AKIAIU5C4FEZYEXAMPLE
&Action=GetBillingAgreementDetails
&AccessToken=IQEBLzAtAhUAjagYW4Jrgw84pCaaIDjrKoEhZXsEXAMPLE
&AmazonBillingAgreementId=C23-1234567-1234567
&ContentType=JSON&JSONCallBack=cb
&MWSAuthToken=amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAMPLE
&SellerId=YOUR_SELLER_ID_HERE
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2013-10-29T10%3A38%3A44.000Z
&Version=2013-01-01
&Signature=gP11oEBaaiQdASWsLDyid18Wn%2BB%2FKZQQtKgpHCtEXAMPLE
    

If you use the payments:shipping_address scope parameter to get the full shipping address before order confirmation, you need to submit two parameters obtained in Step 1: Add a Button widget for buyer authentication:

1. The access token that was returned as the buyer was authenticated. &AccessToken=YOUR_ACCESS_TOKEN
2. The Amazon Billing Agreement ID that was created from a login button or an AddressBook or Wallet widget. &AmazonBillingAgreementId=BILLING_AGREEMENT_IDENTIFIER

For more information about the GetBillingAgreementDetails operation including the request parameters and response elements, see GetBillingAgreementDetails in the Amazon Pay API reference guide.

Recommendations for re-rendering Wallet widgets

In most cases, you do not need to refresh the Wallet widget as it automatically refreshes when a buyer chooses an address from the AddressBook widget. Frequent re-rendering of the Wallet widget affects website performance and causes a poor buyer experience.

Note, however, that the re-rendering of the Wallet widget is actually required when certain constraints are returned in the checkout flow. For example, Amazon Pay might not allow all payment methods for a given transaction. If after calling either the SetBillingAgreementDetails or GetBillingAgreementDetails operation you might see a PaymentMethodNotAllowed constraint in the response. Attempting to confirm a billing agreement that has constraints also returns an error code ConstraintsExist.

To resolve this constraint, you need to either re-render the div of the Wallet widget or ask the buyer to choose a different payment method. To prevent the likelihood of this particular constraint and to improve your buyers' experience, we recommend you set the amount on the billing agreement before rendering the Wallet widget.

For more information about how to simulate constraints for integration testing, see Testing your integration in the Sandbox environment. For more information about constraints on the Billing Agreement object, see Billing agreement constraints in the Amazon Pay API reference.