Add the Sign in with Amazon Button

[Step 2 of 7]The Amazon sign-in and setup process commences when the buyer interacts with the 'Sign in with Amazon' button. Ensure that this button is prominently placed wherever the buyer accesses the sign-in functionality on your website.

In this step, you will configure the Amazon Pay Checkout Session object and then render the ‘Sign in with Amazon’ button. At the end of this step, you will be able to redirect the buyer to an Amazon-hosted page where they can sign in and consent to share their information and save Amazon Pay as a payment method for purchases. The information that is shared enables you to create an account for the buyer and sign them in to your website.

In Seller Central, 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 Sign in with Amazon button, you will need to provide a payload that Amazon Pay can use to determine which buyer details to share and where to redirect the buyer after they sign in.

Instructions for generating button payload:

  • Set the signInReturnUrl parameter to the URL that the buyer should be redirected to after they sign in. The URL will have a checkoutSessionId that you can use to retrieve buyer details appended as a query parameter.

Payload example

{
 "storeId":"amzn1.application-oa2-client.8b5e45312b5248b69eeaStoreId",
 "signInScopes":["name", "email", "postalCode", "shippingAddress", "phoneNumber", "billingAddress"]
 "webCheckoutDetails": {
    "signInReturnUrl": "https://a.com/merchant-page",
    "signInCancelUrl": "optional_cancel_url"
    }
}
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
Amazon Pay store ID. Retrieve this value from Amazon Pay Integration Central: US, EU, JP
signInScopes

Type: list <signInScopes>
Body
The buyer details that you are requesting access for. Note that Amazon Pay will always return buyerId even if no values are set for this parameter

Type: webCheckoutDetails

Parameter
Description
checkoutReviewReturnUrl

Type: string
Checkout review URL provided by the merchant. Amazon Pay will redirect to this URL after the buyer selects their preferred payment instrument and shipping address

Note:
In the Live environment, URLs must use HTTPS protocol. The URL domain must be added to Seller Central. See Add domains to Seller Central for more information.
In the Sandbox environment, you don't need an SSL certificate and can use the HTTP protocol if you're testing on localhost (http://localhost). You don't need to add URLs to the JavaScript Origins in SellerCentral

Max length: 1024 characters/bytes
checkoutResultReturnUrl

Type: string

Checkout result URL provided by the merchant. Amazon Pay will redirect to this URL after completing the transaction

Note: In the Live environment, URLs must use HTTPS protocol. In the Sandbox environment, you don't need an SSL certificate and can use the HTTP protocol if you're testing on localhost (http://localhost)

Max length: 1024 characters/bytes
checkoutCancelUrl

Type: string

Checkout cancellation URL provided by the merchant. Amazon Pay will redirect to this URL if the buyer cancels checkout on any Amazon Pay hosted page

If you do not provide a checkoutCancelUrl, Amazon Pay will redirect the buyer using the following logic:
  • Payment and address selection hosted page - redirect to referrer URL unless it's a different domain than checkoutReviewReturnUrl. If there is a domain mismatch, the buyer will be redirected to checkoutReviewReturnUrl
  • Update payment and address hosted page - redirect to checkoutReviewReturnUrl
  • Declined payment handling hosted page - redirect to checkoutResultReturnUrl
Max length: 1024 characters/bytes
amazonPayRedirectUrl

Type: string
URL provided by Amazon Pay. Merchant will redirect to this page after setting transaction details to complete checkout

Max length: 256 characters/bytes
checkoutMode

Type: string
Specify whether the buyer will return to your website to review their order before completing checkout

Supported values:
  • 'ProcessOrder' - Buyer will complete checkout on the Amazon Pay hosted page immediately after clicking on the Amazon Pay button. paymentDetails is required when using 'ProcessOrder'. addressDetails is also required if you use 'ProcessOrder' with productType set to 'PayAndShip'
signInReturnUrl

Type: string
Amazon Pay will redirect to this URL after the buyer signs in

Note: In the Live environment, URLs must use HTTPS protocol. The URL domain must be added to Seller Central. See Add domains to Seller Central for more information. In the Sandbox environment, you don't need an SSL certificate and can use the HTTP protocol if you're testing on localhost (http://localhost). You don't need to add URLs to the JavaScript Origins in SellerCentral
signInCancelUrl

Type: string
Sign-in cancellation URL provided by the merchant. Amazon Pay will redirect to this URL if the buyer cancels sign-in on the Amazon hosted page

Type: signInScope

Parameter
Description
name
Request access to buyer name
email
Request access to buyer email address
postalCode
Request access to buyer default shipping address postal code and country code
shippingAddress
Request access to buyer default shipping address
billingAddress
Request access to buyer default billing address
phoneNumber
Request access to buyer default billing address phone number

3. Sign the payload

You must secure the payload 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. If you need to change the payload and your button signature is dynamic, you should decouple button render from checkout initialization to avoid re-rendering the button.

Option 1 (recommended): Generate a signature using the helper function provided 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":{"signInReturnUrl":"https://a.com/merchant-page"},"chargePermissionType":"PaymentMethodOnFile","paymentMethodOnFileMetadata":{"setupOnly": true}, "paymentDetails": {"paymentIntent": "Confirm", "canHandlePendingAuthorization": false}}';
    $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 request = new  CreateCheckoutSessionRequest
(
    signInReturnUrl: "https://a.com/merchant-page",
    storeId: "amzn1.application-oa2-client.xxxxx"
);

request.ChargePermissionType = ChargePermissionType.PaymentMethodOnFile;
request.PaymentMethodOnFileMetadata.SetupOnly = true;
request.PaymentDetails.PaymentIntent = PaymentIntent.Confirm;
request.PaymentDetails.CanHandlePendingAuthorization = false;

// generate the button signature
var signature = client.GenerateButtonSignature(request);

// the payload as JSON string that you must assign to the button in the next step
var payload = request.ToJson(); 

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.xxxxxx\",\"webCheckoutDetails\":{\"signInReturnUrl\":\"https://a.com/merchant-page\"},\"chargePermissionType\":\"PaymentMethodOnFile\",\"paymentMethodOnFileMetadata\":{\"setupOnly\": true}, \"paymentDetails\": {\"paymentIntent\": \"Confirm\", \"canHandlePendingAuthorization\": false}}";
String signature = client.generateButtonSignature(payload);

Source code

const fs = require('fs');
const Client = require('@amazonpay/amazon-pay-api-sdk-nodejs');

const config = {
    publicKeyId: 'ABC123DEF456XYZ',
    privateKey: fs.readFileSync('tst/private.pem'),
    region: 'us',
    sandbox: true
};

const testPayClient = new Client.AmazonPayClient(config);
const payload = {
    "webCheckoutDetails": {
        "signInReturnUrl": "https://a.com/merchant-page"
    },
    "storeId": "amzn1.application-oa2-client.xxxxx",
    "chargePermissionType": "PaymentMethodOnFile",   
    "paymentMethodOnFileMetadata": {
        "setupOnly": true
    },
    "paymentDetails": {
        "paymentIntent": "Confirm",
        "canHandlePendingAuthorization": false
    }
};
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 button

Use the values from the previous two 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.

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">
          const amazonPayButton = amazon.Pay.renderButton('#AmazonPayButton', {
              // set checkout environment
              merchantId: 'merchant_id',
              publicKeyId: 'SANDBOX-xxxxxxxxxx',
              ledgerCurrency: 'USD',         
              // customize the buyer experience
              checkoutLanguage: 'en_US',
              productType: 'SignInAndSetup',
              placement: 'Home',
              buttonColor: 'Gold',
              // configure Create Checkout Session request
              createCheckoutSessionConfig: {                     
                  payloadJSON: 'payload', // string generated in step 2
                  signature: 'xxxx', // signature generated in step 3
              }   
          });
      </script>
  </body>

Function parameters

Parameter
Description
merchantId
(required)

Type: string
Amazon Pay merchant account identifier
createCheckoutSessionConfig
(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 'Sign in with Amazon' 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
  • 'PaymentMethodList' - A list of available payment methods, displayed in checkout or in the payment method section of your site
  • 'Onboarding' - Displayed after the buyer signs in to your site
  • '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'
  • JP merchants - 'JPY'
productType

Type: string
Product type selected for checkout

Supported values:
  • 'SignInAndSetup' - Offer Amazon Sign-in & Setup. Select this product type if you need the buyer to create an account and sign in to your app or website. The buyer will consent to share their information and save Amazon Pay for purchases.
buttonColor

Type: string
Color of the 'Sign in with Amazon' 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: 
  • US merchants - 'en_US'
  • EU/UK merchants - 'en_GB', 'de_DE', 'fr_FR', 'it_IT', 'es_ES'
  • JP merchants - 'ja_JP'
sandbox

Type: boolean
Sets button to Sandbox environment

You do not have to set this parameter if your publicKeyId has an environment prefix (for example: SANDBOX-AFVX7ULWSGBZ5535PCUQOY7B)

Default value: false