Step 1: Add a Button widget for buyer authentication
Prerequisite: Complete all requirements in the Prerequisites section before beginning this integration step.
The first widget that you need to embed and present to your buyers is the Amazon Pay button widget. This widget displays the button that lets buyers know that they can use their Amazon credentials (email address and password) to sign in and use Amazon Pay to pay for their order on your site.
Assuming that you have added the necessary JavaScript code in the head section of your website (as described in the Prerequisites section), you can embed the button of your choice by adding the following code:
<div id="AmazonPayButton"/>
<script>
function renderButton() {
var authRequest;
OffAmazonPayments.Button("AmazonPayButton", "YOUR_MERCHANT_ID ", {
type: "ENTER_TYPE_PARAMETER",
color: "ENTER_COLOR_PARAMETER",
size: "ENTER_SIZE_PARAMETER",
language: "LANGUAGE",
authorization: function() {
loginOptions =
{scope: "ENTER_SCOPES", popup: "ENTER_POPUP_PARAMETER"};
authRequest = amazon.Login.authorize (loginOptions,
"YOUR_REDIRECT_URL ");
},
onError: function(error) {
// your error handling code
}
});
};
</script>
The code sample above defines the division in your webpage that is used to render the button. Place this code in the HTML where you want the button to appear.
When you add the button code to your site, you need to replace parameters in the code sample with your own values. The following sections describe how to replace text in the code sample:
Related topics:
YOUR_MERCHANT_ID
Replace YOUR_MERCHANT_ID with your own Merchant-ID, which you received during registration. If you are not sure what your Merchant-ID is, sign in to Seller Central and go to Integration > MWS Access Key to view your Merchant ID.
Type
The type parameter is an optional parameter for indicating the type of button image that you want to choose for your webpage. Note that if you decide not to specify a value for type, the Login with Amazon button is set as the default value.
The following table shows the valid type parameter values, button descriptions, and sample button images.
| Type codes | Button description | Button example |
| LwA |
Specifies the Login with Amazon button.
This is the default button if type is not specified. |
|
| PwA | Specifies the Amazon Pay button. |
|
Color
The color parameter is an optional parameter for selecting a button color. This table shows the valid color code values, color descriptions, and color samples.
| Color codes | Color description | Color example |
| Gold | Gold (default) |
|
| LightGray | Light gray |
|
| DarkGray | Dark gray |
|
Language
The language parameter is an optional parameter for associating a language with a Login with Amazon or an Amazon Pay button. This is useful for offering multi-language support for an Amazon Pay and Login with Amazon experience for buyers on your website.
For example, a French-speaking buyer wants to make a purchase from a German website. The buyer, either by changing the language preference settings in their browser or by making a selection from a language switcher on your website, can view Amazon Pay components in French.
The following table shows the valid language parameter values.
| Language values | Language description | Buttons |
| de-DE | Germany's German |
|
| en-GB | UK English |
|
| es-ES | Spain's Spanish |
|
| fr-FR | France's French |
|
| it-IT | Italy's Italian |
|
If you pass a language other than those listed above or no language parameter at all, the language defaults to the buyer's browser language. If the buyer's browser language preference setting is not one of the languages listed above, the language defaults to English. We recommend that you set the button language according to the language currently shown on your website. If your website allows language switching, the language of the Amazon Pay buttons should also be set to switch.
For more information see Multi-language integration.
Size
The size parameter is an optional parameter for selecting a button size. For more information about button size options, see the Button guidelines.
| Regular | Retina |
|
|
The actual size rendered depends on the type of button selected:
| Parameter | Type | Size |
|
|
LwA - Specifies the Login with Amazon button. |
|
|
|
PwA - Specifies the Amazon Pay button. |
|
Scope
The value of the parameter scope that you choose influences both the content returned in the response of the call and the type of consent screen Amazon Pay shows to the buyer to secure their permission for sharing their information.
You may use a combination of the following scope parameters:
| Scope parameter | Description | Requirements |
| profile | Gives access to the full user profile (username, email-address, user-id) after login | |
| profile:user_id | Gives access only to the user-id from the user profile after login | |
| payments:widget | Required to show the Amazon Pay widgets (Address and Wallet widget) on your page. If used without the two parameters below, it gives access to the full shipping address after ConfirmOrderReference call and to the full billing address after successful authorisation. | |
| payments:shipping_address | Gives access to the full shipping address via the GetOrderReferenceDetails API call as soon as an address has been chosen in the address widget | Requires scope parameter payments:widget AccessToken set in GetOrderReferenceDetails call |
| payments:billing_address | Gives access to the full billing address via the GetOrderReferenceDetails API call as soon as a payment method has been chosen in the Wallet widget | Requires scope parameter payments:widget AccessToken set in GetOrderReferenceDetails call |
Example: scope: profile payments:widget payments:shipping_address payments:billing_address
The payments:shipping_address provides access to the buyer's shipping address. To retrieve the full shipping address, you need to call the getOrderReferenceDetails API. For more information, see "Getting the shipping address from Amazon" in Step 2: Add the AddressBook and Wallet widgets or GetOrderReferenceDetails in the Amazon Pay API reference guide.
Popup
The popup parameter determines whether the buyer is presented with a pop-up window to authenticate or if the buyer is instead redirected to an Amazon Pay page to authenticate.
Use one of the following popup parameters:
- true - An Amazon Pay authentication screen is presented in a pop-up dialog where buyers can authenticate without ever leaving your website. This value is recommended for desktops where the button widget is presented on a secure page. Note that this option requires that the button resides on an HTTPS page with a valid TLS/SSL certificate.
- false - The buyer is redirected to an Amazon Pay page within the same browser window. This value is recommended for smartphone-optimized devices or if you are rendering the button widget on a non-secure page. Note that the redirect URL must use HTTPS protocol and have a valid TLS/SSL certificate. For more information, see Use redirect authentication experience.
Default: popup: true
When you embed an Amazon Pay button with the pop-up parameter set to true, the buyer is asked for their Amazon credentials (email address and password):
As you can see in the previous screenshot, you can add your company logo to the authentication window. You can do this on Seller Central by clicking Settings and then clicking Integration Settings.
YOUR_REDIRECT_URL
The redirect URL is a parameter that determines which page the buyer is redirected to after successfully authenticating. For example, after a successful authentication, you might want to take the buyer to the next page in your checkout pipeline to collect their shipping address and/or payment method details. Note that in case you use "popup:false" in your button code, which means you use the redirect login experience, you have to add all the redirect URLs to the access list in the Seller Central > Integration Central settings for your application.
Error handling code
We also recommend that you implement an onError handler in your code. The onError code is optional, but it can save you considerable effort with troubleshooting integration issues. For more information, see Testing your integration in the Sandbox environment .
Adding a logout option
After a user has signed in, you should add a logout option (often a hyperlink) to your website. The logout option should delete any cached tokens and remove the user's profile information (like their name) from your website, and then your website can present the Login button again.
If you are using the Login with Amazon SDK for JavaScript, you can call the amazon.Login.logout method to delete any cached tokens. For example:
<script>
document.getElementById('Logout').onclick = function() {
amazon.Login.logout();
};
</script>
Subsequent calls to amazon.Login.authorize presents the login screen, by default.