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>
For more details about these JavaScript blocks, check the section Step 3: Add a button widget.
- 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:
- One-page checkout
- Multi-page checkout
- 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 - 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. We recommend that you use a min-width of 300px.
/*
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;
}
Checkout workflow
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.
Note: Because errors can occur as you follow these steps, be sure to write your code in a way that prevents errors in one functionality from influencing the correct operation of other elements. Also, implement a comprehensive logging, especially for the error and exception handling, so you can solve problems quickly and with less effort.
- Make sure that you received and stored the AccessToken.
- Render the AddressBook widget.
- Get the Shipping address with getOrderReferenceDetails API call.
- Check whether the destination is supported by the shop configuration.
- Determine delivery options and costs according to the destination.
- Submit preliminary order total by setOrderReferenceDetails API call.
- (Re-)render the Wallet widget after the setOrderReferenceDetails call.
- Get the billing address with getOrderReferenceDetails API call.
- 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 chosen.
Requirements:
- Scope parameter payments:shipping_address for the full shipping address
- Scope parameter payments:billing_address for the billing address
- Parameter AccessToken set 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 their 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:
- Identify changes to update the addresses by sending a GetOrderReferenceDetails API call. Whether or not you need to do this depends on your integration. If you show shipping cost, delivery options (for example, express and standard), custom taxes, and anything else that depends on the selected shipping address that are on the same page with the AddressBook widget, then you will probably need to request the new address with any change in the widgets. If you just show the widget here and anything else, depending on the customer's selection on the next page, in your checkout flow, doing that once before the next page is loaded is sufficient.
- Make sure that a shipping address and a payment method is selected before you let your customer proceed with checkout.
In rare cases the widgets are empty so that no entry can be automatically selected. This can happen in the following cases:
For the AddressBook 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?
Because Amazon requires the payment method to be confirmed once when a new address is entered for fraud prevention. The set of available payment instruments in the Wallet widget might vary for different shipping addresses. To show the right set of payment methods, the Wallet widget is automatically invalidated and re-rendered on any selection change in the AddressBook widget. As a result, the Wallet widget might become empty after a different shipping address is selected.
Proceeding to checkout without a valid selection in the widgets results in errors when the order and, subsequently the payment are confirmed. Therefore, before you let your customer proceed to checkout make sure that:
- There was at least one onAddressSelect event.
- 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, certain payment instruments that are available in an Amazon customer account might not be usable. When that happens, the corresponding payment instruments are deactivated in the Wallet widget to prevent their selection. To be able to deactivate such payment instrument, submit the preliminary order total after the shipping address was selected and before the Wallet widget is rendered. Doing so is usually not possible when both widgets are shown on the same page, so 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 re-render the Wallet widget, a payment method might be selected that will be excluded later upon submitting the final order total when order is confirmed, resulting in a constraint in the OrderReferenceObject and also in an error for the ConfirmOrderReference API call. For more information, see Order reference constraints and Sandbox simulate them when testing your integration
AddressBook widget in multipage checkout
<!-- Place this code in your HTML where you would like the AddressBook widget to appear. -->
<div id="addressBookWidgetDiv"> </div>
<script>
window.onAmazonLoginReady = function() {amazon.Login.setClientId('YOUR-CLIENT-ID'); };
window.onAmazonPaymentsReady = function() {
addressBookWidget = 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 AddressBook 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.
}
});
addressBookWidget.bind("addressBookWidgetDiv");
};
</script>
<script async="async"
src='https://static-eu.payments-amazon.com/OffAmazonPayments/gbp/sandbox/lpa/js/Widgets.js'>
</script>
Wallet widget in multipage checkout
The following code can be used for integrations where the AddressBook and Wallet widgets 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() {
walletWidget = 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.
}
});
walletWidget.setPresentmentCurrency("GBP"); // ISO-4217 currency code, merchant is expected to enter valid list of currency supported by Amazon Pay.
walletWidget.bind("walletWidgetDiv");
};
</script>
<script async="async"
src='https://static-eu.payments-amazon.com/OffAmazonPayments/gbp/sandbox/lpa/js/Widgets.js'>
</script>
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
<!-- 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() {
addressBookWidget = 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.
// We don't recommend that you explicitly refresh it.
},
design: {
designMode: 'responsive'
},
onReady: function(orderReference) {
// Enter code here you want to be executed
// when the AddressBook 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.
}
});
addressBookWidget.bind("addressBookWidgetDiv");
walletWidget = 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.
}
});
walletWidget.setPresentmentCurrency("GBP"); // ISO-4217 currency code, merchant is expected to enter a valid currency supported by Amazon Pay.
walletWidget.bind("walletWidgetDiv");
};
</script>
<script async="async"
src='https://static-eu.payments-amazon.com/OffAmazonPayments/gbp/sandbox/lpa/js/Widgets.js'>
</script>