Steps to integrate with Amazon Pay's hosted update page

You can integrate with Amazon Pay’s solution that handles the payment and address update for the buyer.

Follow below steps to integrate the solution:

1. Add the Amazon Pay script
2. Generate the Create Checkout Session payload
3. Sign the payload
4. Render an UI element and call Amazon Pay's init checkout API
5. Set up Instant Payment Notifications (IPN)

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

Provide a payload that Amazon Pay will use to create a Checkout Session object that will be used for the update. Amazon Pay will use the Checkout Session object to manage the buyer’s activity during the update.

Instructions for generating button payload for the update flow:

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.
Set chargePermissionId to the Saved Wallet charge permission id value stored for the buyer.
Set chargePermissionType to PaymentMethodOnFile
Set productType as “PayAndShip”
- If buyer intends to update an address
- If buyer intends to update payment method for a charge permission id that has an associated address
- If you intend to update theSaved Wallet Charge Permission Id from a “PayOnly” product type to a “PayAndShip” productType.
Set productType as “PayOnly” if the Saved Wallet Charge Permission Id stored on your systems was of type “PayOnly” and buyer's intention is to update the payment method alone.
Provide details for paymentMethodOnFileMetadata: Provide setupOnly = true to initiate a update payment method or address flow for a Saved Wallet charge permission id.
Set paymentIntent = Confirm since there is no transaction happening in update flow.

Optional integrations steps:

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 samples how to handle common use-cases.

Payload example

{
    "webCheckoutDetails": {
        "checkoutResultReturnUrl": "https://a.com/merchant-result-page"
    },
    "storeId": "amzn1.application-oa2-client.8b5e45312b5248b69eeaStoreId",
    "chargePermissionId": "B01-0000000-0000000",
    "chargePermissionType": "PaymentMethodOnFile",
    "paymentMethodOnFileMetadata": {
        "setupOnly": true
    },
    "paymentDetails": {
        "paymentIntent": "Confirm",
        "canHandlePendingAuthorization": false        
    }    
    "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	Amazon Pay store ID. Retrieve this value from Amazon 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' - Default billing address phone number 'billingAddress' - Default billing address Default value: all buyer information except billing address is requested if the `scopes` parameter is not set
chargePermissionId Type: string	Body	The buyer's Saved Wallet charge permission id with the merchant
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.

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.

Option 1 (recommended): Generate a signature using the helper function provided in the Amazon Pay SDKs.

<?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":{"checkoutResultReturnUrl":"https://example.com/review.html"},"chargePermissionId": "B01-0000000-0000000","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
(
    checkoutReviewReturnUrl: "https://example.com/review.html",
    storeId: "amzn1.application-oa2-client.xxxxx",
    chargePermissionId: "B01-0000000-0000000"
);

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

// generate the payload 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\":{\"checkoutResultReturnUrl\":\"https://example.com/review.html\"},\"chargePermissionId\":\"B01-0000000-0000000\",\"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": {
        "checkoutResultReturnUrl": "https://example.com/review.html"
    },
    "storeId": "amzn1.application-oa2-client.xxxxx",
    "chargePermissionId": "B01-0000000-0000000",
    "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 an UI element and call Amazon Pay's init checkout API

Any UI element can be rendered to trigger the payment method and/or address update. UI element click should be bound to call amazon pay’s init update function as shown in the example below. Once the UI element is clicked buyer will be redirected to Amazon’s page where they can update the payment method or address.

After the successful update buyer is redirected back to the checkoutResultReturnUrl that was set in the payload.

NOTE: The amzon.Pay.initUpdate() function is not yet available, to test the update flow, please use amazon.Pay.initCheckout() function instead.

Code sample

<body>
    <button onclick="initAmazonPayUpdate()">Update</button>
    <script src="https://static-na.payments-amazon.com/checkout.js"></script>
    <script type="text/javascript" charset="utf-8">
        function initAmazonPayUpdate() {
            amazon.Pay.initUpdate({
                merchantId: 'merchant_id',
                ledgerCurrency: 'USD',
                sandbox: false,            
                checkoutLanguage: 'en_US',
                productType: 'PayAndShip',
                createCheckoutSessionConfig: {                     
                    payloadJSON: 'payload', 
                    signature: 'xxxx',
                    publicKeyId: 'xxxxxxxxxx'
                }   
            });
        }
    </script>
</body>

<body>
    <button onclick="initAmazonPayUpdate()">Update</button>
    <script src="https://static-eu.payments-amazon.com/checkout.js"></script>
    <script type="text/javascript" charset="utf-8">
        function initAmazonPayUpdate() {
            amazon.Pay.initUpdate({
                merchantId: 'merchant_id',
                ledgerCurrency: 'EUR',
                sandbox: false,            
                checkoutLanguage: 'en_GB',
                productType: 'PayAndShip',
                createCheckoutSessionConfig: {                     
                    payloadJSON: 'payload', 
                    signature: 'xxxx',
                    publicKeyId: 'xxxxxxxxxx'
                }   
            });
        }
    </script>
</body>

<body>
    <button onclick="initAmazonPayUpdate()">Update</button>
    <script src="https://static-eu.payments-amazon.com/checkout.js"></script>
    <script type="text/javascript" charset="utf-8">
        function initAmazonPayUpdate() {
            amazon.Pay.initUpdate({
                merchantId: 'merchant_id',
                ledgerCurrency: 'GBP',
                sandbox: false,            
                checkoutLanguage: 'en_GB',
                productType: 'PayAndShip',
                createCheckoutSessionConfig: {                     
                    payloadJSON: 'payload', 
                    signature: 'xxxx',
                    publicKeyId: 'xxxxxxxxxx'
                }   
            });
        }
    </script>
</body>

<body>
    <button onclick="initAmazonPayUpdate()">Update</button>
    <script src="https://static-fe.payments-amazon.com/checkout.js"></script>
    <script type="text/javascript" charset="utf-8">
        function initAmazonPayUpdate() {
            amazon.Pay.initUpdate({
                merchantId: 'merchant_id',
                ledgerCurrency: 'JPY',
                sandbox: false,            
                checkoutLanguage: 'ja_JP',
                productType: 'PayAndShip',
                createCheckoutSessionConfig: {                     
                    payloadJSON: 'payload', 
                    signature: 'xxxx',
                    publicKeyId: 'xxxxxxxxxx'
                }   
            });
        }
    </script>
</body>

5. Set up Instant Payment Notifications (IPN)

Set up IPNs to receive notifications whenever buyers update their payment method or address.