Add the HAQM Pay Button

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

In this step, you will configure the HAQM Pay Checkout Session object and then render the HAQM Pay button. At the end of this step, you will be able to redirect the buyer to an HAQM Pay hosted page where they can select their preferred payment method.

You must add the domains where the HAQM Pay button will be rendered to Seller Central. See Add domains to Seller Central for more information.

1. Add the HAQM Pay script
2. Generate the Create Checkout Session payload
3. Sign the payload
4. Render the button

1. Add the HAQM Pay script

Add the HAQM Pay script to your HTML file. Be sure you select the correct region.

<script src="http://static-na.payments-haqm.com/checkout.js"></script>

<script src="http://static-eu.payments-haqm.com/checkout.js"></script>

<script src="http://static-fe.payments-haqm.com/checkout.js"></script>

2. Generate the Create Checkout Session payload

To render the HAQM Pay button, you will need to provide a payload that HAQM Pay will use to create a Checkout Session object. You will use the Checkout Session object to manage the buyer’s active session on your website. 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.

Instructions for generating button payload:

Set checkoutResultReturnUrl parameter to the URL that the buyer is redirected to after they select their preferred payment method. The Checkout Session ID will be appended as a query parameter to the provided URL.
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.
Set chargePermissionType to "PaymentMethodOnFile"
Provide details for paymentMethodOnFileMetadata:
- Provide setupOnly = false to initiate a Saved Wallet Setup with Purchase flow.
Only if the buyer has a recurring item in the cart:
- Set recurringMetadata.frequency to increase buyer confidence. If you do not provide a value in this step, you are required to set a value before the buyer can complete checkout. HAQM Pay only uses this information in buyer communication.
- It is optional but recommended to set recurringMetadata.amount. Note you are still responsible for calling Create Charge to charge the buyer for the recurring amount each billing cycle, including the first one.

Optional integrations steps:

Use the deliverySpecifications parameter to specify shipping restrictions and prevent buyers from selecting unsupported addresses from their HAQM address book. See address restriction samples for samples how to handle common use-cases.
If you registered for HAQM 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.

Payload example when buyer has one-time chargeable items in cart

{
    "webCheckoutDetails": {
        "checkoutReviewReturnUrl": "http://a.com/merchant-review-page"
    },
    "storeId": "amzn1.application-oa2-client.8b5e45312b5248b69eeaStoreId",
    "scopes": ["name", "email", "phoneNumber", "billingAddress"],
    "chargePermissionType": "PaymentMethodOnFile",
    "paymentMethodOnFileMetadata": {
        "setupOnly": false
    },    
    "deliverySpecifications": {
        "specialRestrictions": ["RestrictPOBoxes"],
        "addressRestrictions": {
            "type": "Allowed",
            "restrictions": {
                "US": {
                    "statesOrRegions": ["WA"],
                    "zipCodes": ["95050", "93405"]
                },
                "GB": {
                    "zipCodes": ["72046", "72047"]
                },
                "IN": {
                    "statesOrRegions": ["AP"]
                },
                "JP": {}
            }
        }
    }
}

Payload example when buyer has a recurring item in cart

{
    "webCheckoutDetails": {
        "checkoutReviewReturnUrl": "http://a.com/merchant-review-page"
    },
    "storeId": "amzn1.application-oa2-client.8b5e45312b5248b69eeaStoreId",
    "scopes": ["name", "email", "phoneNumber", "billingAddress"],
    "chargePermissionType": "PaymentMethodOnFile",
    "paymentMethodOnFileMetadata": {
        "setupOnly": false
    },
    "recurringMetadata": {
        "frequency": { 
            "unit": "Month", 
            "value": "1" 
        },
        "amount": { 
            "amount": "30",
            "currencyCode": "USD"
        }
    },        
    "deliverySpecifications": {
        "specialRestrictions": ["RestrictPOBoxes"],
        "addressRestrictions": {
            "type": "Allowed",
            "restrictions": {
                "US": {
                    "statesOrRegions": ["WA"],
                    "zipCodes": ["95050", "93405"]
                },
                "GB": {
                    "zipCodes": ["72046", "72047"]
                },
                "IN": {
                    "statesOrRegions": ["AP"]
                },
                "JP": {}
            }
        }
    }
}

Payload example when buyer has one-time and recurring items in cart

The amount for one-time checkout items should be a part of chargeAmount field
If the charge for first billing cycle is included in the chargeAmount field, then merchant should skip calling Create Charge for the first cycle of the subscription.
Merchants are responsible for calling Create Charge to charge the buyer for the recurring amount each billing cycle

{
    "webCheckoutDetails": {
        "checkoutReviewReturnUrl": "http://a.com/merchant-review-page"
    },
    "storeId": "amzn1.application-oa2-client.8b5e45312b5248b69eeaStoreId",
    "scopes": ["name", "email", "phoneNumber", "billingAddress"],
    "chargePermissionType": "PaymentMethodOnFile",
    "paymentMethodOnFileMetadata": {
        "setupOnly": false
    },
    "recurringMetadata": {
        "frequency": { 
            "unit": "Month", 
            "value": "1" 
        },
        "amount": { 
            "amount": "30",
            "currencyCode": "USD"
        }
    },
    "paymentDetails": {
        "paymentIntent": "Authorize",
        "chargeAmount": {
            "amount": "1",
            "currencyCode": "USD"
        }   
    },        
    "deliverySpecifications": {
        "specialRestrictions": ["RestrictPOBoxes"],
        "addressRestrictions": {
            "type": "Allowed",
            "restrictions": {
                "US": {
                    "statesOrRegions": ["WA"],
                    "zipCodes": ["95050", "93405"]
                },
                "GB": {
                    "zipCodes": ["72046", "72047"]
                },
                "IN": {
                    "statesOrRegions": ["AP"]
                },
                "JP": {}
            }
        }
    }
}

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	HAQM Pay store ID. Retrieve this value from HAQM Pay Integration Central: US, EU, JP
scopes Type: list <scope>	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: 'name' - Buyer name 'email' - Buyer email 'phoneNumber' - Buyer phone number. You must also request `billingAddress` scope or use `payAndShip` productType to retrieve the billing address or shipping address phone number. 'billingAddress' - Default billing address Default value: all buyer information except billing address is requested if the `scopes` parameter is not set
chargePermissionType Type: string	Body	The type of Charge Permission requested Supported values: 'OneTime' - The Charge Permission can only be used for a single order 'Recurring' - The Charge Permission can be used for recurring orders 'PaymentMethodOnFile' - The Charge Permission can be used for Saved Wallet orders Default value: 'OneTime"
paymentDetails Type: paymentDetails	Body	Payment details specified by the merchant such as the amount and method for charging the buyer Modifiable: Multiple times before the buyer is redirected to the `amazonPayReturnUrl`
merchantMetadata Type: merchantMetadata	Body	External order details provided by the merchant Modifiable: Multiple times before the buyer is redirected to the `amazonPayReturnUrl`
paymentMethodOnFileMetadata Type: paymentMethodOnFileMetadata	Body	Metadata about how Saved Wallet charge permission will be used.
recurringMetadata Type: recurringMetadata	Body	Metadata about how the Charge Permission will be used to support recurring payment use cases. HAQM Pay only uses this information in buyer communication.

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 HAQM 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 HAQM\Pay\API\Client($amazonpay_config);
    $payload = '{"storeId":"amzn1.application-oa2-client.xxxxx","webCheckoutDetails":{"checkoutReviewReturnUrl":"http://example.com/review.html"},"chargePermissionType":"PaymentMethodOnFile","paymentMethodOnFileMetadata":{"setupOnly": false}, "paymentDetails": {"paymentIntent": "AuthorizeWithCapture", "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
(
    checkoutReviewReturnUrl: "http://example.com/review.html",
    storeId: "amzn1.application-oa2-client.xxxxx"
);

request.ChargePermissionType = ChargePermissionType.PaymentMethodOnFile;
request.PaymentMethodOnFileMetadata.SetupOnly = false;
request.PaymentDetails.PaymentIntent = PaymentIntent.AuthorizeWithCapture;
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 (HAQMPayClientException e) {
    e.printStackTrace();
}

HAQMPayClient client = new HAQMPayClient(payConfiguration);

String payload = "{\"storeId\":\"amzn1.application-oa2-client.xxxxxx\",\"webCheckoutDetails\":{\"checkoutReviewReturnUrl\":\"http://example.com/review.html\"},\"chargePermissionType\":\"PaymentMethodOnFile\",\"paymentMethodOnFileMetadata\":{\"setupOnly\": false}, \"paymentDetails\": {\"paymentIntent\": \"AuthorizeWithCapture\", \"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.HAQMPayClient(config);
const payload = {
    "webCheckoutDetails": {
        "checkoutReviewReturnUrl": "http://example.com/review.html"
    },
    "storeId": "amzn1.application-oa2-client.xxxxx",
    "chargePermissionType": "PaymentMethodOnFile",   
    "paymentMethodOnFileMetadata": {
        "setupOnly": false
    },
    "paymentDetails": {
        "paymentIntent": "AuthorizeWithCapture",
        "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 HAQM 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 HAQM Pay checkout immediately on button click. If you need control of the click event, you can decouple button render and checkout initiation. See HAQM Pay script for more info.

Code sample

<body>
    <div id="HAQMPayButton"></div>
    <script src="http://static-na.payments-haqm.com/checkout.js"></script>
    <script type="text/javascript" charset="utf-8">
        amazon.Pay.renderButton('#HAQMPayButton', {
            // set checkout environment
            merchantId: 'merchant_id',
            publicKeyId: 'SANDBOX-xxxxxxxxxx',
            ledgerCurrency: 'USD',            
            // customize the buyer experience
            checkoutLanguage: 'en_US',
            productType: 'PayAndShip',
            placement: 'Other',
            buttonColor: 'Gold',
            // configure Create Checkout Session request
            createCheckoutSessionConfig: {                     
                payloadJSON: 'payload', // string generated in step 2
                signature: 'xxxx' // signature generated in step 3
            }   
        });
    </script>
</body>

<body>
    <div id="HAQMPayButton"></div>
    <script src="http://static-eu.payments-haqm.com/checkout.js"></script>
    <script type="text/javascript" charset="utf-8">
        amazon.Pay.renderButton('#HAQMPayButton', {
            // set checkout environment
            merchantId: 'merchant_id',
            publicKeyId: 'SANDBOX-xxxxxxxxxx',
            ledgerCurrency: 'EUR',              
            // customize the buyer experience
            checkoutLanguage: 'en_GB',
            productType: 'PayAndShip',
            placement: 'Other',
            buttonColor: 'Gold',
            // configure Create Checkout Session request
            createCheckoutSessionConfig: {                     
                payloadJSON: 'payload', // string generated in step 2
                signature: 'xxxx' // signature generated in step 3
            }   
        });
    </script>
</body>

<body>
    <div id="HAQMPayButton"></div>
    <script src="http://static-eu.payments-haqm.com/checkout.js"></script>
    <script type="text/javascript" charset="utf-8">
        amazon.Pay.renderButton('#HAQMPayButton', {
            // set checkout environment
            merchantId: 'merchant_id',
            publicKeyId: 'SANDBOX-xxxxxxxxxx',
            ledgerCurrency: 'GBP',            
            // customize the buyer experience
            checkoutLanguage: 'en_GB',
            productType: 'PayAndShip',
            placement: 'Other',
            buttonColor: 'Gold',
            // configure Create Checkout Session request
            createCheckoutSessionConfig: {                     
                payloadJSON: 'payload', // string generated in step 2
                signature: 'xxxx' // signature generated in step 3
            }   
        });
    </script>
</body>

<body>
    <div id="HAQMPayButton"></div>
    <script src="http://static-fe.payments-haqm.com/checkout.js"></script>
    <script type="text/javascript" charset="utf-8">
        amazon.Pay.renderButton('#HAQMPayButton', {
            // set checkout environment
            merchantId: 'merchant_id',
            publicKeyId: 'SANDBOX-xxxxxxxxxx',
            ledgerCurrency: 'JPY',            
            // customize the buyer experience
            checkoutLanguage: 'ja_JP',
            productType: 'PayAndShip',
            placement: 'Other',
            buttonColor: 'Gold',
            // configure Create Checkout Session request
            createCheckoutSessionConfig: {                     
                payloadJSON: 'payload', // string generated in step 2
                signature: 'xxxx' // signature generated in step 3
            }   
        });
    </script>
</body>

<body>
    <div id="HAQMPayButton"></div>
    <script src="http://static-na.payments-haqm.com/checkout.js"></script>
    <script type="text/javascript" charset="utf-8">
        amazon.Pay.renderButton('#HAQMPayButton', {
            // set checkout environment
            merchantId: 'merchant_id',
            ledgerCurrency: 'USD',
            sandbox: true,               
            // customize the buyer experience
            checkoutLanguage: 'en_US',
            productType: 'PayAndShip',
            placement: 'Other',
            buttonColor: 'Gold',
            // configure Create Checkout Session request
            createCheckoutSessionConfig: {                     
                payloadJSON: 'payload', // string generated in step 2
                signature: 'xxxx', // signature generated in step 3
                publicKeyId: 'xxxxxxxxxx' 
            }   
        });
    </script>
</body>

<body>
    <div id="HAQMPayButton"></div>
    <script src="http://static-eu.payments-haqm.com/checkout.js"></script>
    <script type="text/javascript" charset="utf-8">
        amazon.Pay.renderButton('#HAQMPayButton', {
            // set checkout environment
            merchantId: 'merchant_id',
            ledgerCurrency: 'EUR',
            sandbox: true,               
            // customize the buyer experience
            checkoutLanguage: 'en_GB',
            productType: 'PayAndShip',
            placement: 'Other',
            buttonColor: 'Gold',
            // configure Create Checkout Session request
            createCheckoutSessionConfig: {                     
                payloadJSON: 'payload', // string generated in step 2
                signature: 'xxxx', // signature generated in step 3
                publicKeyId: 'xxxxxxxxxx' 
            }   
        });
    </script>
</body>

<body>
    <div id="HAQMPayButton"></div>
    <script src="http://static-eu.payments-haqm.com/checkout.js"></script>
    <script type="text/javascript" charset="utf-8">
        amazon.Pay.renderButton('#HAQMPayButton', {
            // set checkout environment
            merchantId: 'merchant_id',
            ledgerCurrency: 'GBP',
            sandbox: true,               
            // customize the buyer experience
            checkoutLanguage: 'en_GB',
            productType: 'PayAndShip',
            placement: 'Other',
            buttonColor: 'Gold',
            // configure Create Checkout Session request
            createCheckoutSessionConfig: {                     
                payloadJSON: 'payload', // string generated in step 2
                signature: 'xxxx', // signature generated in step 3
                publicKeyId: 'xxxxxxxxxx' 
            }   
        });
    </script>
</body>

<body>
    <div id="HAQMPayButton"></div>
    <script src="http://static-fe.payments-haqm.com/checkout.js"></script>
    <script type="text/javascript" charset="utf-8">
        amazon.Pay.renderButton('#HAQMPayButton', {
            // set checkout environment
            merchantId: 'merchant_id',
            ledgerCurrency: 'JPY',
            sandbox: true,               
            // customize the buyer experience
            checkoutLanguage: 'ja_JP',
            productType: 'PayAndShip',
            placement: 'Other',
            buttonColor: 'Gold',
            // configure Create Checkout Session request
            createCheckoutSessionConfig: {                     
                payloadJSON: 'payload', // string generated in step 2
                signature: 'xxxx', // signature generated in step 3
                publicKeyId: 'xxxxxxxxxx' 
            }   
        });
    </script>
</body>

Function parameters

Parameter	Description
merchantId (required) Type: string	HAQM Pay merchant account identifier
publicKeyId (required) Type: string	Credential provided by HAQM Pay. See Get you publicKeyId for more info You must also set the `sandbox` parameter if your `publicKeyId` does not have an environment prefix
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 HAQM 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' JP merchants - 'JPY'
productType Type: string	Product type selected for checkout Supported values: 'PayAndShip' - Offer checkout using buyer's HAQM wallet and address book. Select this product type if you need the buyer's shipping details 'PayOnly' - Offer checkout using only the buyer's HAQM wallet. Select this product type if you do not need the buyer's shipping details 'SignIn' - Offer HAQM Sign-in. Select this product type if you need buyer details before the buyer starts HAQM Pay checkout. See HAQM Sign-in for more information. Default value: 'PayAndShip'
buttonColor Type: string	Color of the HAQM Pay button Supported values: 'Gold', 'LightGray', 'DarkGray' Default value: 'Gold'
checkoutLanguage Type: string	Language used to render the button and text on HAQM Pay hosted pages. Please note that supported language(s) is dependent on the region that your HAQM 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