Add the Amazon Pay Button
[Step 2 of 7] The Amazon Pay checkout experience starts when the buyer clicks on the Amazon Pay button. Unlike the one-time checkout flow, the buyer will complete checkout on the Amazon Pay Buy Now hosted checkout page after clicking on the Amazon Pay button.
In this step, you will configure the Amazon Pay Checkout Session object and then render the Amazon Pay button. At the end of this step, you will be able to redirect the buyer to the Amazon Pay single page checkout where they can select their preferred shipping address and payment instrument.
The buyer will be able to review and change shipping options and review order details and complete checkout on this page.
You must add the domains where the Amazon Pay button will be rendered to Seller Central. See Add domains to Seller Central for more information.
1. Add the Amazon Pay script
Add the Amazon Pay script to your HTML file. Be sure you select the correct region.
<script src="https://static-na.payments-amazon.com/checkout.js"></script>
<script src="https://static-eu.payments-amazon.com/checkout.js"></script>
<script src="https://static-fe.payments-amazon.com/checkout.js"></script>
2. Generate the Create Checkout Session payload
To render the Amazon Pay button, you will need to provide a payload that Amazon Pay will use to to start customers checkout.
The payload has the same structure as the request body for the Create Checkout Session API. Providing the payload as part of the button removes the need to call this API. In the payload, you must provide all details required for the buyer to complete checkout. As the major difference to the one-time integration, you will not need to pass webCheckoutDetails
, as the experience will now remain in-context.
Instructions for generating button payload:
- Specify the buyer information you need to complete checkout using the
scopes
parameter. If you do not set this value, all buyer information except billing address will be requested as part of onInitCheckout callback. - For EU/UK region: If you need to collect additional info from the buyer, you can request BuyerAdditionalInfo by specifying the matching scopes parameter. Once requested, the buyer has to provide the data before completing checkout. The info will be shared as part of the
onCompleteCheckout
callback (coming soon).
Optional integrations steps:
- Use the
deliverySpecifications
parameter to specify shipping restrictions and prevent buyers from selecting unsupported addresses from their Amazon address book. See address restriction samples for samples how to handle common use-cases. - If you registered for Amazon Pay in the EU or UK, you can use the
presentmentCurrency
parameter to charge your buyer using a different supported currency. See multi-currency integration for more info. - Use the onInitCheckout and onShippingAddressSelection callback to validate if you support the shipping address.
Payload example
{
"storeId": "amzn1.application-oa2-client.8b5e45312b5248b69eeaStoreId",
"scopes": ["name", "email", "phoneNumber", "billingAddress"],
"paymentDetails": {
"paymentIntent": "AuthorizeWithCapture",
"canHandlePendingAuthorization":false,
"softDescriptor": "Descriptor"
},
"deliverySpecifications": {
"specialRestrictions": ["RestrictPOBoxes"],
"addressRestrictions": {
"type": "Allowed",
"restrictions": {
"US": {
"statesOrRegions": ["WA"],
"zipCodes": ["95050", "93405"]
},
"GB": {
"zipCodes": ["72046", "72047"]
},
"IN": {
"statesOrRegions": ["AP"]
},
"JP": {}
}
}
},
}
Name
|
Location
|
Description
|
storeId (required) Type: string |
Body
|
Amazon Pay store ID. Retrieve this value from Amazon Pay Integration Central: US, EU, JP
|
paymentDetails (required) Type: paymentDetails |
Body
|
Payment details specified by the merchant, such as the amount and method for charging the buyer NOTE: `paymentIntent` and `canHandlePendingAuthorization` are the only fields supported from the `paymentDetails` object for a Buy Now integration. |
scopes Type: list<string> |
Body
|
The buyer details that you're requesting access to. Specify whether you need shipping address using button productType parameter in Step 4.Supported values:
scopes parameter is not set
|
chargePermissionType Type: string |
Body
|
The type of Charge Permission requested Supported values for Buy Now:
|
deliverySpecifications Type: deliverySpecifications |
Body
|
Specify shipping restrictions to prevent buyers from selecting unsupported addresses from their Amazon address book
|
merchantMetadata Type: merchantMetadata |
Body
|
Merchant-provided order details
|
platformId Type: string |
Body
|
Merchant identifier of the Solution Provider (SP). Only SPs should use this field. Modifiable: Multiple times before the buyer is redirected to the amazonPayReturnUrl .
|
providerMetadata Type: providerMetadata |
Body
|
Payment service provider (PSP)-provided order details Only PSPs should use these fields |
3. Render the button
Use the values from the previous step to render the Amazon Pay button to a HTML container element. The button will be responsive and it will inherit the size of the container element, see responsive button logic for details.
The code below will initiate Amazon Pay checkout immediately on button click. Event handlers need to be registered and defined in the button JavaScript code, to receive and communicate cart-level details to Amazon Pay that will be rendered on the checkout page. The implementation of the event handlers are detailed in the step Provide Event Handlers.
Code sample
<body>
<div id="AmazonPayButton"></div>
<script src="https://static-na.payments-amazon.com/checkout.js"></script>
<script type="text/javascript" charset="utf-8">
amazon.Pay.renderJSButton('#AmazonPayButton', {
// set checkout environment
merchantId: 'merchant_id',
ledgerCurrency: 'USD',
sandbox: 'true',
// customize the buyer experience
checkoutLanguage: 'en_US',
productType: 'PayAndShip',
placement: 'Cart',
buttonColor: 'Gold',
estimatedOrderAmount: {"amount": "109.99", "currencyCode": "USD"},
// provide checkout configuration generated in previous step
checkoutSessionConfig: {
"storeId": "store_id",
"scopes": ["name", "email", "phoneNumber", "billingAddress"],
"paymentDetails": {
"paymentIntent": "AuthorizeWithCapture",
"canHandlePendingAuthorization": "false"
},
},
// add placeholders for event handlers for user interaction
/** Invokes when initiated checkout and authenticated **/
onInitCheckout: function (event) {
// return initial cart details, total amount, tax, delivery options
},
/** Invokes when customer has selected different shipping address **/
onShippingAddressSelection: function (event) {
// return updated cart details, total amount, tax, delivery options
},
/** Invokes when customer clicks Pay Now **/
onCompleteCheckout: function (event) {
// Amazon Pay provides checkout session id, final billing address and payment descriptor.
},
/** Invokes when customer has selected different shipping Method **/
onDeliveryOptionSelection: function (event) {
// return updated cart details, total amount, tax, delivery options
},
/** Invokes when customer abandons the checkout **/
onCancel: function (event) {
// take customer back to cart page or product details page based on merchant checkout
}
});
</script>
</body>
<body>
<div id="AmazonPayButton"></div>
<script src="https://static-eu.payments-amazon.com/checkout.js"></script>
<script type="text/javascript" charset="utf-8">
amazon.Pay.renderJSButton('#AmazonPayButton', {
// set checkout environment
merchantId: 'merchant_id',
ledgerCurrency: 'EUR',
sandbox: 'true',
// customize the buyer experience
checkoutLanguage: 'de_DE',
productType: 'PayAndShip',
placement: 'Cart',
buttonColor: 'Gold',
estimatedOrderAmount: {"amount": "109.99", "currencyCode": "EUR"},
// provide checkout configuration generated in previous step
checkoutSessionConfig: {
"storeId": "store_id",
"scopes": ["name", "email", "phoneNumber", "billingAddress"],
"paymentDetails": {
"paymentIntent": "AuthorizeWithCapture",
"canHandlePendingAuthorization": "false"
},
},
// add placeholders for event handlers for user interaction
/** Invokes when initiated checkout and authenticated **/
onInitCheckout: function (event) {
// return initial cart details, total amount, tax, delivery options
},
/** Invokes when customer has selected different shipping address **/
onShippingAddressSelection: function (event) {
// return updated cart details, total amount, tax, delivery options
},
/** Invokes when customer clicks Pay Now **/
onCompleteCheckout: function (event) {
// Amazon Pay provides checkout session id, final billing address and payment descriptor.
},
/** Invokes when customer has selected different shipping Method **/
onDeliveryOptionSelection: function (event) {
// return updated cart details, total amount, tax, delivery options
},
/** Invokes when customer abandons the checkout **/
onCancel: function (event) {
// take customer back to cart page or product details page based on merchant checkout
}
});
</script>
</body>
<body>
<div id="AmazonPayButton"></div>
<script src="https://static-eu.payments-amazon.com/checkout.js"></script>
<script type="text/javascript" charset="utf-8">
amazon.Pay.renderJSButton('#AmazonPayButton', {
// set checkout environment
merchantId: 'merchant_id',
ledgerCurrency: 'GBP',
sandbox: 'true',
// customize the buyer experience
checkoutLanguage: 'en_GB',
productType: 'PayAndShip',
placement: 'Cart',
buttonColor: 'Gold',
estimatedOrderAmount: {"amount": "109.99", "currencyCode": "GBP"},
// provide checkout configuration generated in previous step
checkoutSessionConfig: {
"storeId": "store_id",
"scopes": ["name", "email", "phoneNumber", "billingAddress"],
"paymentDetails": {
"paymentIntent": "AuthorizeWithCapture",
"canHandlePendingAuthorization": "false"
},
},
// add placeholders for event handlers for user interaction
/** Invokes when initiated checkout and authenticated **/
onInitCheckout: function (event) {
// return initial cart details, total amount, tax, delivery options
},
/** Invokes when customer has selected different shipping address **/
onShippingAddressSelection: function (event) {
// return updated cart details, total amount, tax, delivery options
},
/** Invokes when customer clicks Pay Now **/
onCompleteCheckout: function (event) {
// Amazon Pay provides checkout session id, final billing address and payment descriptor.
},
/** Invokes when customer has selected different shipping Method **/
onDeliveryOptionSelection: function (event) {
// return updated cart details, total amount, tax, delivery options
},
/** Invokes when customer abandons the checkout **/
onCancel: function (event) {
// take customer back to cart page or product details page based on merchant checkout
}
});
</script>
</body>
<body>
<div id="AmazonPayButton"></div>
<script src="https://static-fe.payments-amazon.com/checkout.js"></script>
<script type="text/javascript" charset="utf-8">
amazon.Pay.renderJSButton('#AmazonPayButton', {
// set checkout environment
merchantId: 'merchant_id',
ledgerCurrency: 'JPY',
sandbox: 'true',
// customize the buyer experience
checkoutLanguage: 'ja_JP',
productType: 'PayAndShip',
placement: 'Cart',
buttonColor: 'Gold',
// provide checkout configuration generated in previous step
checkoutSessionConfig: {
"storeId": "store_id",
"scopes": ["name", "email", "phoneNumber", "billingAddress"],
"paymentDetails": {
"paymentIntent": "AuthorizeWithCapture",
"canHandlePendingAuthorization": "false"
},
},
// add placeholders for event handlers for user interaction
/** Invokes when initiated checkout and authenticated **/
onInitCheckout: function (event) {
// return initial cart details, total amount, tax, delivery options
},
/** Invokes when customer has selected different shipping address **/
onShippingAddressSelection: function (event) {
// return updated cart details, total amount, tax, delivery options
},
/** Invokes when customer clicks Pay Now **/
onCompleteCheckout: function (event) {
// Amazon Pay provides checkout session id, final billing address and payment descriptor.
},
/** Invokes when customer has selected different shipping Method **/
onDeliveryOptionSelection: function (event) {
// return updated cart details, total amount, tax, delivery options
},
/** Invokes when customer abandons the checkout **/
onCancel: function (event) {
// take customer back to cart page or product details page based on merchant checkout
}
});
</script>
</body>
Function parameters
Parameter
|
Description
|
merchantId (required) Type: string |
Amazon Pay merchant account identifier
|
checkoutSessionConfig (required) Type: buttonConfig |
Create Checkout Session configuration. This is a required field if you use PayAndShip or PayOnly productType |
placement (required) Type: string |
Placement of the Amazon Pay button on your website Supported values:
|
ledgerCurrency (required) Type: string |
Ledger currency provided during registration for the given merchant identifier Supported values:
|
estimatedOrderAmount Type: price |
This is the estimated checkout order amount, it does not have to match the final order amount if the buyer updates their order after starting checkout. Amazon Pay will use this value to assess transaction risk and prevent buyers from selecting payment methods that can't be used to process the order |
productType Type: string |
Product type selected for checkout Supported values:
|
buttonColor Type: string |
Color of the Amazon Pay button Supported values: 'Gold', 'LightGray', 'DarkGray' Default value: 'Gold' |
checkoutLanguage Type: string |
Language used to render the button and text on Amazon Pay hosted pages. Please note that supported language(s) is dependent on the region that your Amazon Pay account was registered for Supported values:
|
sandbox Type: boolean |
Sets button to Sandbox environment
Default value: false |