This is a draft guide. Content is subject to change.

Add the Amazon Pay Button

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


1. Create an Amazon Pay checkout session

Set up an endpoint on your server to Create Checkout Session. Use the Checkout Session object to customize and manage your buyer experience- from the time the buyer clicks on the Amazon Pay button, until they complete checkout. Note that in a later step, to start the checkout flow, you will need the value of the CheckoutSessionId parameter from the Create Checkout Session response.

Use the checkoutReviewReturnUrl parameter to specify the URL which the buyer is redirected to, after they select their preferred shipping address and payment method.

Best practice: set up your endpoint on the same domain as your website to avoid Cross-Origin Resource Sharing complications.

Request

curl "https://pay-api.amazon.com/:environment/:version/checkoutSessions/" \
-X POST
-H "x-amz-pay-idempotency-key: AVLo5tI10BHgEk2jEXAMPLEKEY"
-H "x-amz-pay-authorization: Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-d @request_body

Request body

{
    webCheckoutDetail: {
        checkoutReviewReturnUrl:"https://a.com/merchant-review-page"
    },
    storeId: "amzn1.application-oa2-client.8b5e45312b5248b69eeaStoreId"
}  

Request parameters

Name
Location
Description
x-amz-pay-idempotency-key
(required)

Type: string
Header
Idempotency key to safely retry requests
webCheckoutDetail
(required)

Type: webCheckoutDetail
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

Response

{
  checkoutSessionId: "checkoutId-1",
  webCheckoutDetail: {
    checkoutReviewReturnUrl:"https://a.com/merchant-review-page"
  },
  storeId: "amzn1.application-oa2-client.c48db267f2d44b6bbe2f65aadee22ea6",
  statusDetail:{
    state: "Open",
    reasonCode: "",
    reasonDescription: "",
    lastUpdatedTimestamp: "" 
  },
  constraints: [{
    constraintCode: "CheckoutReviewReturnUrlNotSet"
    constraintDescription: "You must specify the URL for Amazon to be 
    able to redirect to your checkoutReviewReturnUrl page"
  }],
  creationTimestamp: "20190714T155300Z",
  expirationTimestamp: "20190715T155300Z"
}

2. 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>

3. Render the button

Call amazon.Pay.renderButton to render the Amazon Pay button to an HTML container element. The button will be responsive, and inherit the size of the container element according to the following logic:

  • If no width or height is provided, the container will be resized to 200w x 45h.
  • If only either width or height is provided, the container will be resized to match a 200w x 45h ratio. The minimum supported dimension is 150w x 45h and the maximum is 500w x 193h.

The Amazon Pay script will make an AJAX request using the configuration provided for the createCheckoutSession button parameter. The response must be in JSON format.

The only required parameter is the url. Specify the endpoint you set up in Step 1 as its value. You can customize the request by changing the HTTP request method. If your endpoint does not return the entire Checkout Session object, use extractAmazonCheckoutSessionId to specify the Checkout Session ID parameter in the response.

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', {
            merchantId: 'merchant_id',
            createCheckoutSession: {
                url: 'https://mystore/amazonpay/createcheckoutsession'
            },
            sandbox: true, // dev environment
            ledgerCurrency: 'USD', // Amazon Pay account ledger currency
            checkoutLanguage: 'en_US', // render language
            productType: 'PayAndShip', // checkout type
            placement: 'Cart' // button placement
        });
    </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', {
            merchantId: 'merchant_id',
            createCheckoutSession: {
                url: 'https://mystore/amazonpay/createcheckoutsession'
            },
            sandbox: true, // dev environment
            ledgerCurrency: 'EUR', // Amazon Pay account ledger currency
            checkoutLanguage: 'en_GB', // render language
            productType: 'PayAndShip', // checkout type
            placement: 'Cart' // button placement
        });
    </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', {
            merchantId: 'merchant_id',
            createCheckoutSession: {
                url: 'https://mystore/amazonpay/createcheckoutsession'
            },
            sandbox: true, // dev environment
            ledgerCurrency: 'GBP', // Amazon Pay account ledger currency
            checkoutLanguage: 'en_GB', // render language
            productType: 'PayAndShip', // checkout type
            placement: 'Cart' // button placement
        });
    </script>
</body>

Function parameters

Parameter
Description
merchantId
(required)

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

Type: createCheckoutSession
Configuration for calling your endpoint to Create Checkout Session. The response must be in JSON format
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'
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