Gracias por tu visita. Esta página solo está disponible en inglés.
 Step 2: Add the AddressBook and Wallet widgets | Amazon Pay

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 that 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:

 
<!--- please 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 re-renders 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 7: 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 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 AddressBook widget to collect addresses from the buyer, refer to the Integrating without the AddressBook widget section of this guide.

To 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>
  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
    }
  }).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 the sample 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 the optimal 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 Amazon Pay 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:

  Two-column widget One-column widget
Parameter Recommended dimension Valid dimensions Recommended dimension Valid dimensions
width 400px 400px - 600px 300px 300px - 399px
height 228px 228px - 400px 228px 228px - 400px

Following a successful authentication, the buyer sees the AddressBook widget where you specified the widget to render, similar to this 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.

Note: 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.

Note: If you are using both the Amazon 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 from Amazon Pay

In many cases, to calculate shipping charges and taxes, you need to obtain the buyer's shipping address. 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 Login with Amazon button or the Amazon Pay button and set the payments:shipping_address scope parameter in the JavaScript that 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: To work properly, all of your API calls must be signed. To sign your API requests, you need Amazon MWS keys. You can get these keys by signing in to Seller Central, clicking the Integration tab, and then viewing the MWS Access Key section. 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.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:38:44.000Z
&Version=2013-01-01
&Signature=gP11oEBaaiQdASWsLDyid18Wn+B/KZQQtKgpHCtEXAMPLE
    

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.