Add the Amazon Pay Button

[Step 2 of 9] The Amazon Pay checkout experience starts when the buyer clicks on the Amazon Pay button. Add the button wherever the buyer starts checkout, such as on the mini cart, shopping cart page, or checkout page.

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 an Amazon Pay hosted page where they can select their preferred shipping address and payment instrument.


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>

2. Generate the Create Checkout Session payload

Amazon Pay will use the createCheckoutSessionConfig value to create a Checkout Session object. You will use the Checkout Session in later steps to manage the buyer’s active session on your website.

Use the request body for the Create Checkout Session API to build the payload. In the payload, set the checkoutReviewReturnUrl parameter to the URL that the buyer is redirected to after they select their preferred shipping address and payment method. The Checkout Session ID will be appended as a query parameter.

Optional integration step

Use the deliverySpecifications parameter to specify shipping restrictions to prevent buyers from selecting unsupported addresses from their Amazon address book. See address restriction samples for examples of common use-cases.

payloadJSON example

{
    "webCheckoutDetails": {
        "checkoutReviewReturnUrl":"https://a.com/merchant-review-page"
    },
    "storeId":"amzn1.application-oa2-client.8b5e45312b5248b69eeaStoreId",
    "deliverySpecifications": {
        "specialRestrictions": ["RestrictPOBoxes"],
        "addressRestrictions": {
            "type":"Allowed",
            "restrictions": {
                "US": {
                    "statesOrRegions": ["WA"],
                    "zipCodes": ["95050", "93405"]
                },
                "GB": {
                    "zipCodes": ["72046", "72047"]
                },
                "IN": {
                    "statesOrRegions": ["AP"]
                },
            }
        }
    }
}  
Name
Location
Description
webCheckoutDetails
(required)

Type: webCheckoutDetails
Body
URLs associated to the Checkout Session used to complete checkout. The URLs must use HTTPS protocol
storeId
(required)

Type: string
Body
Login with Amazon client ID. Do not use the application ID

Retrieve this value from "Login with Amazon" in Seller Central
deliverySpecifications

Type: deliverySpecifications
Body
Specify shipping restrictions to prevent buyers from selecting unsupported addresses from their Amazon address book

3 Sign the payload

You must secure payloadJSON using a signature. The payload does not include a timestamp so you can re-use the signature as long as the payload does not change.

Option 1 (recommended): Generate a signature using the helper function in the Amazon Pay SDKs. The signature generated by the helper function is only valid for the button and not for API requests.

<?php 
    include 'vendor/autoload.php'; 
    $amazonpay_config = array( 
        'public_key_id' => 'MY_PUBLIC_KEY_ID', 
        'private_key' => 'keys/private.pem', 
        'region' => 'US', 
        'sandbox' => true 
    ); 
    $client = new Amazon\Pay\API\Client($amazonpay_config); 
    $payload = '{"storeId":"amzn1.application-oa2-client.xxxxx","webCheckoutDetails":{"checkoutReviewReturnUrl":"https://localhost/test/CheckoutReview.php"}}'; 
    $signature = $client->generateButtonSignature($payload); 
    echo $signature . "\n"; 
?>
Source code
var payConfiguration = new ApiConfiguration ( 
    region: Region.Europe, 
    environment: Environment.Sandbox, 
    publicKeyId: "MY_PUBLIC_KEY_ID", 
    privateKey: "PATH_OR_CONTENT_OF_MY_PRIVATE_KEY" 
); 
var canonicalBuilder = new CanonicalBuilder(); 
var signatureHelper = new SignatureHelper(payConfiguration, canonicalBuilder); 
string payload = '{"storeId":"amzn1.application-oa2-client.xxxxx","webCheckoutDetails":{"checkoutReviewReturnUrl":"https://localhost/test/CheckoutReview.php"}}'; 
string signature = signatureHelper.GenerateSignature(payload, payConfiguration.PrivateKey);
Source code
PayConfiguration payConfiguration = null; 
try { 
    payConfiguration = new PayConfiguration() 
            .setPublicKeyId("YOUR_PUBLIC_KEY_ID") 
            .setRegion(Region.YOUR_REGION_CODE) 
            .setPrivateKey("YOUR_PRIVATE_KEY_STRING") 
            .setEnvironment(Environment.SANDBOX);
}catch (AmazonPayClientException e) { 
    e.printStackTrace(); 
} 
AmazonPayClient client = new AmazonPayClient(payConfiguration); 
String payload = '{"storeId":"amzn1.application-oa2-client.xxxxx","webCheckoutDetails":{"checkoutReviewReturnUrl":"https://localhost/test/CheckoutReview.php"}}'; 
String signature = client.generateButtonSignature(payload);
Source code
html const fs = require('fs'); 
const uuidv4 = require('uuid/v4'); 
const Client = require('../src/client'); 
const config = { 
    publicKeyId: 'ABC123DEF456XYZ', 
    privateKey: fs.readFileSync('tst/private.pem'), 
    region: 'us', 
    sandbox: true 
}; 
const testPayClient = new Client.AmazonPayClient(config); 
const payload = { 
    webCheckoutDetails: { 
        checkoutReviewReturnUrl: 'https://localhost/test/checkoutReview.html' 
    }, 
    storeId: 'amzn1.application-oa2-client.xxxxx' 
}; 
const signature = testPayClient.generateButtonSignature(payload);
Source code

Option 2: Build the signature manually by following steps 2 and 3 of the signing requests guide.


4. Render the Amazon Pay button

Use the values from the previous to steps 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. If you need control of the click event, you can decouple button render and checkout initiation. See Amazon Pay script for more info.

Note: The payload passed in the createCheckoutSessionConfig should be exactly the same as the payload that is signed in the previous step.

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.renderButton('#AmazonPayButton', {
            // set checkout environment
            merchantId: 'merchant_id',
            ledgerCurrency: 'USD',
            sandbox: true,               
            // customize the buyer experience
            checkoutLanguage: 'en_US',
            productType: 'PayAndShip',
            placement: 'Cart',
            // configure Create Checkout Session request
            createCheckoutSessionConfig: {                     
                payloadJSON: payload, // payload generated in step 2
                signature: 'xxxx', // signature generatd in step 3
                publicKeyId: 'xxxxxxxxxx'
            }   
        });
    </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.renderButton('#AmazonPayButton', {
            // set checkout environment
            merchantId: 'merchant_id',
            ledgerCurrency: 'EUR',
            sandbox: true,               
            // customize the buyer experience
            checkoutLanguage: 'en_GB',
            productType: 'PayAndShip',
            placement: 'Cart',
            // configure Create Checkout Session request
            createCheckoutSessionConfig: {                     
                payloadJSON: payload, // payload generated in step 2
                signature: 'xxxx', // signature generatd in step 3
                publicKeyId: 'xxxxxxxxxx'
            }   
        });
    </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.renderButton('#AmazonPayButton', {
            // set checkout environment
            merchantId: 'merchant_id',
            ledgerCurrency: 'GBP',
            sandbox: true,               
            // customize the buyer experience
            checkoutLanguage: 'en_GB',
            productType: 'PayAndShip',
            placement: 'Cart',
            // configure Create Checkout Session request
            createCheckoutSessionConfig: {                     
                payloadJSON: payload, // payload generated in step 2
                signature: 'xxxx', // signature generatd in step 3
                publicKeyId: 'xxxxxxxxxx'
            }   
        });
    </script>
</body>

Function parameters

Parameter
Description
merchantId
(required)

Type: string
Amazon Pay merchant account identifier
createCheckoutSessionConfig
(required)

Type: checkoutSessionConfig
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:
  • 'Home' - Initial or main page
  • 'Product' - Product details page
  • 'Cart' - Cart review page before buyer starts checkout
  • 'Checkout' - Any page after buyer starts checkout
  • 'Other' - Any page that doesn't fit the previous descriptions
ledgerCurrency
(required)

Type: string
Ledger currency provided during registration for the given merchant identifier

Supported values:
  • US merchants - 'USD'
  • EU merchants - 'EUR'
  • UK merchants - 'GBP'
productType

Type: string
Product type selected for checkout

Supported values:
  • 'PayAndShip' - Offer checkout using the buyer's Amazon wallet and address book. Select this product type if you need the buyer's shipping details
  • 'PayOnly' - Offer checkout using only the buyer's Amazon wallet. Select this product type if you do not need the buyer's shipping details
  • 'SignIn' - Offer Amazon Sign-in. Select this product type if you need buyer details before the buyer starts Amazon Pay checkout.

Default value: 'PayAndShip'
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: 
  • US merchants - 'en_US'
  • EU/UK merchants - 'en_GB', de_DE', 'fr_FR', 'it_IT', 'es_ES'
sandbox

Type: boolean
Sets button to Sandbox environment

Default value: false