Display shipping and payment info

[Step 3 of 10] The buyer is redirected to checkoutReviewReturnUrl after they select their preferred shipping address and payment instrument. The Amazon Pay checkout session ID will be included as a query parameter.

In this step, you will use the checkout session ID to get checkout info (such as shipping address and payment instrument) and to enable checkout preference updates. At the end of this step, you will be able to present the buyer with an order summary and give them the option of updating their preferred shipping and payment instrument before they complete checkout.

1. Get shipping and payment info
2. Enable shipping and payment updates

1. Get shipping and payment info

Get Checkout Session to retrieve checkout info, such as buyer email, shipping address, and payment information. Use the response to display checkout information, offer shipping options if applicable, and calculate additional costs.

Note that you can only retrieve checkout info using Get Checkout Session while the Checkout Session object is in an Open state. Additionally, shipping address will only be returned if the Checkout Session has PayAndShip product type. After a successful checkout, you can use Get Charge Permission to retrieve checkout info.

Important:

For protection against buyer disputes, you should display the shipping address that you receive from Amazon Pay as read-only text. Enable shipping and payment updates so that buyers can select a different shipping address from their Amazon address book. More information about Amazon Pay Payment Protection Plan here: US, UK, EU, JP.
Use the paymentDescriptor value returned in Get Checkout Session response to represent the buyer-selected payment instrument. Amazon Pay may dynamically return a different value to optimize checkout conversion.
Verify the address returned in the Get Checkout Session is supported by your business requirements even if you use the deliverySpecifications parameter to limit which addresses your buyer can select from their Amazon address book. If the address returned is not supported, please ask the buyer to select a different one.
Do not display checkout info such as shipping address or buyer email to anyone besides the buyer who initiated checkout. Implement validation (for example: browser session verification) in case someone besides the buyer gains access to the Checkout Session ID.

Request


curl "https://pay-api.amazon.com/:version/checkoutSessions/:checkoutSessionId"

-X GET

-H "authorization:Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"

-H "x-amz-pay-date:20201012T235046Z"


curl "https://pay-api.amazon.com/:environment/:version/checkoutSessions/:checkoutSessionId"

-X GET

-H "authorization:Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"

-H "x-amz-pay-date:20201012T235046Z"

Request parameters

Name	Location	Description
CheckoutSessionId (required) Type: string	Path Parameter	Checkout session identifier

Sample Code

<?php
    include 'vendor/autoload.php';

    $amazonpay_config = array(
        'public_key_id' => 'YOUR_PUBLIC_KEY_ID', 
        'private_key'   => 'keys/private.pem',
        'region'        => 'YOUR_REGION_CODE',
        'algorithm'     => 'AMZN-PAY-RSASSA-PSS-V2'
    );
        
    try {
        $client = new Amazon\Pay\API\Client($amazonpay_config);
        $result = $client->getCheckoutSession('bd504926-f659-4ad7-a1a9-9a747aaf5275');
        if ($result['status'] === 200) {
            $response = json_decode($result['response'], true);
            $checkoutSessionState = $response['statusDetails']['state'];
            $chargeId = $response['chargeId'];
            $chargePermissionId = $response['chargePermissionId'];

            // NOTE: Once Checkout Session moves to a "Completed" state, buyer and shipping
            // details must be obtained from the getChargePermission() function call instead
            $buyerName = $response['buyer']['name'];
            $buyerAddress = $response['buyer']['shippingAddress'];
        } else {
            // check the error
            echo 'status=' . $result['status'] . '; response=' . $result['response'] . "\n";
        }
    } catch (Exception $e) {
        // handle the exception
        echo $e;
    }
?>

using Amazon.Pay.API.Types;
using Amazon.Pay.API.WebStore;
using Amazon.Pay.API.WebStore.Types;
using Amazon.Pay.API.WebStore.CheckoutSession;

public class Sample
{
    public WebStoreClient InitiateClient()
    {
        // set up config
        var payConfiguration = new ApiConfiguration
        (
            region: Region.YOUR_REGION_CODE,
            publicKeyId: "YOUR_PUBLIC_KEY_ID",
            privateKey: "PATH_OR_CONTENT_OF_YOUR_PRIVATE_KEY",
            algorithm: AmazonSignatureAlgorithm.V2
        );

        // init API client
        var client = new WebStoreClient(payConfiguration);

        return client;
    }

    public void GetCheckoutSession(string checkoutSessionId)
    {
        // send the request
        CheckoutSessionResponse result = client.GetCheckoutSession(checkoutSessionId);

        // check if API call was successful
        if (!result.Success)
        {
            // handle the API error (use Status field to get the numeric error code)
        }
        // do something with the result, for instance:
        Buyer buyer = result.Buyer;
        Address shippingAddress = result.ShippingAddress;
    }
}

import com.amazon.pay.api.AmazonPayResponse;
import com.amazon.pay.api.PayConfiguration;
import com.amazon.pay.api.WebstoreClient;
import com.amazon.pay.api.exceptions.AmazonPayClientException;
import com.amazon.pay.api.types.Region;

public void sample() {
    PayConfiguration payConfiguration = null;
    try {
        payConfiguration = new ApiConfiguration()
            .setPublicKeyId("YOUR_PUBLIC_KEY_ID")
            .setRegion(Region.YOUR_REGION_CODE)
            .setPrivateKey("YOUR_PRIVATE_KEY")
            .setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");

        WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
        AmazonPayResponse response = webstoreClient.getCheckoutSession("bd504926-f659-4ad7-a1a9-9a747aaf5275");
    } catch (AmazonPayClientException e) {
        e.printStackTrace();
    }
}

const fs = require('fs');
const Client = require('@amazonpay/amazon-pay-api-sdk-nodejs');
    
const config = {
    publicKeyId: 'YOUR_PUBLIC_KEY_ID',
    privateKey: fs.readFileSync('tst/private.pem'),
    region: 'YOUR_REGION_CODE',
    algorithm: 'AMZN-PAY-RSASSA-PSS-V2' 
};    
                    
const testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.getCheckoutSession('bd504926-f659-4ad7-a1a9-9a747aaf5275');

response.then(function (result) {
    console.log(result.data);
}).catch(err => {
    console.log(err);
});

<?php
    include 'vendor/autoload.php';

    $amazonpay_config = array(
        'public_key_id' => 'YOUR_PUBLIC_KEY_ID', 
        'private_key'   => 'keys/private.pem',
        'region'        => 'YOUR_REGION_CODE',
        'sandbox'       => true,
        'algorithm'     => 'AMZN-PAY-RSASSA-PSS-V2'
    );
        
    try {
        $client = new Amazon\Pay\API\Client($amazonpay_config);
        $result = $client->getCheckoutSession('bd504926-f659-4ad7-a1a9-9a747aaf5275');
        if ($result['status'] === 200) {
            $response = json_decode($result['response'], true);
            $checkoutSessionState = $response['statusDetails']['state'];
            $chargeId = $response['chargeId'];
            $chargePermissionId = $response['chargePermissionId'];

            // NOTE: Once Checkout Session moves to a "Completed" state, buyer and shipping
            // details must be obtained from the getChargePermission() function call instead
            $buyerName = $response['buyer']['name'];
            $buyerAddress = $response['buyer']['shippingAddress'];
        } else {
            // check the error
            echo 'status=' . $result['status'] . '; response=' . $result['response'] . "\n";
        }
    } catch (Exception $e) {
        // handle the exception
        echo $e;
    }
?>

using Amazon.Pay.API.Types;
using Amazon.Pay.API.WebStore;
using Amazon.Pay.API.WebStore.Types;
using Amazon.Pay.API.WebStore.CheckoutSession;

public class Sample
{
    public WebStoreClient InitiateClient()
    {
        // set up config
        var payConfiguration = new ApiConfiguration
        (
            region: Region.YOUR_REGION_CODE,
            environment: Environment.Sandbox,
            publicKeyId: "YOUR_PUBLIC_KEY_ID",
            privateKey: "PATH_OR_CONTENT_OF_YOUR_PRIVATE_KEY",
            algorithm: AmazonSignatureAlgorithm.V2
        );

        // init API client
        var client = new WebStoreClient(payConfiguration);

        return client;
    }

    public void GetCheckoutSession(string checkoutSessionId)
    {
        // send the request
        CheckoutSessionResponse result = client.GetCheckoutSession(checkoutSessionId);

        // check if API call was successful
        if (!result.Success)
        {
            // handle the API error (use Status field to get the numeric error code)
        }
        // do something with the result, for instance:
        Buyer buyer = result.Buyer;
        Address shippingAddress = result.ShippingAddress;
    }
}

import com.amazon.pay.api.AmazonPayResponse;
import com.amazon.pay.api.PayConfiguration;
import com.amazon.pay.api.WebstoreClient;
import com.amazon.pay.api.exceptions.AmazonPayClientException;
import com.amazon.pay.api.types.Environment;
import com.amazon.pay.api.types.Region;

public void sample() {
    PayConfiguration payConfiguration = null;
    try {
        payConfiguration = new ApiConfiguration()
            .setPublicKeyId("YOUR_PUBLIC_KEY_ID")
            .setRegion(Region.YOUR_REGION_CODE)
            .setPrivateKey("YOUR_PRIVATE_KEY")
            .setEnvironment(Environment.SANDBOX)
            .setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");

        WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
        AmazonPayResponse response = webstoreClient.getCheckoutSession("bd504926-f659-4ad7-a1a9-9a747aaf5275");
    } catch (AmazonPayClientException e) {
        e.printStackTrace();
    }
}

const fs = require('fs');
const Client = require('@amazonpay/amazon-pay-api-sdk-nodejs');
    
const config = {
    publicKeyId: 'YOUR_PUBLIC_KEY_ID',
    privateKey: fs.readFileSync('tst/private.pem'),
    region: 'YOUR_REGION_CODE',
    sandbox: true,
    algorithm: 'AMZN-PAY-RSASSA-PSS-V2' 
};    
                    
const testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.getCheckoutSession('bd504926-f659-4ad7-a1a9-9a747aaf5275');

response.then(function (result) {
    console.log(result.data);
}).catch(err => {
    console.log(err);
});

Response

{
    "checkoutSessionId": "bd504926-f659-4ad7-a1a9-9a747aaf5275",
    "webCheckoutDetails": {
        "checkoutReviewReturnUrl": "https://a.com/merchant-review-page",
        "checkoutResultReturnUrl": null,
        "checkoutCancelUrl": null,
        "amazonPayRedirectUrl": null
    },
    "chargePermissionType": "Recurring",   
    "recurringMetadata": {
        "frequency": { 
            "unit": "Month", 
            "value": "1" 
        },
        "amount": { 
            "amount": "30",
            "currencyCode": "USD"
        }
    },
    "productType": "PayAndShip",
    "paymentDetails": {
        "paymentIntent": null,
        "canHandlePendingAuthorization": false,
        "chargeAmount": null,
        "totalOrderAmount": null,
        "softDescriptor": null,
        "presentmentCurrency": null,
        "allowOvercharge": null,
        "extendExpiration": null
    },
    "merchantMetadata": {
        "merchantReferenceId": null,
        "merchantStoreName": null,
        "noteToBuyer": null,
        "customInformation": null
    },
    "supplementaryData": null, // Amazon Pay system data
    "buyer": {
        "buyerId": "buyerId",
        "name": "name-1",
        "email": "name@amazon.com",
        "phoneNumber": "800-000-0000",
        "primeMembershipTypes": null
    },
    "billingAddress": {
        "name": "Work",
        "addressLine1": "440 Terry Ave",
        "addressLine2": "",
        "addressLine3": "",
        "city": "Seattle",
        "county": "King",    
        "district": "Seattle",
        "stateOrRegion": "WA",
        "postalCode": "98121",
        "countryCode": "US",
        "phoneNumber": "800-000-0000"
    },
    "paymentPreferences": [
        {
            "paymentDescriptor": "Visa ****1111 (Amazon Pay)"
        }
    ],
    "statusDetails": {
        "state": "Open",
        "reasonCode": null,
        "reasonDescription": null,
        "lastUpdatedTimestamp": "20191015T204327Z"
    },
    "shippingAddress": {  // Null for PayOnly product type
        "name": "Susie Smith",
        "addressLine1": "10 Ditka Ave",
        "addressLine2": "Suite 2500",
        "addressLine3": null,
        "city": "Chicago",
        "county": null,
        "district": null,
        "stateOrRegion": "IL",
        "postalCode": "60602",
        "countryCode": "US",
        "phoneNumber": "800-000-0000"
    },
    "platformId": null,
    "chargePermissionId": null,
    "chargeId": null,
    "constraints": [
        {
            "constraintId": "ChargeAmountNotSet",
            "description": "chargeAmount is not set."
        },
        {
            "constraintId": "CheckoutResultReturnUrlNotSet",
            "description": "checkoutResultReturnUrl is not set."
        },
        {
            "constraintId": "PaymentIntentNotSet",
            "description": "paymentIntent is not set."
        }
    ],
    "creationTimestamp": "20191015T204313Z",
    "expirationTimestamp": "20191016T204313Z",
    "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"]
                },
                "JP": {}
          }
        }
    },
    "providerMetadata": {
        "providerReferenceId": null
    },
    "checkoutButtonText": null,
    "releaseEnvironment": "Sandbox"
}

2. Enable shipping and payment updates

Use amazon.Pay.bindChangeAction() to bind click events to HTML elements, so that when the element is clicked, the buyer can select a different shipping address or payment method. Be sure to Get Checkout Session after the buyer returns to your site to retrieve updated checkout info.

Step 1. 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>

Step 2. Use amazon.Pay.bindChangeAction() to bind click events to HTML elements on your page. You can specify whether the buyer is editing shipping address or payment method by using the changeAction parameter.

Changing address (only relevant if Checkout Session product type is PayAndShip):

<script type="text/javascript" charset="utf-8">
  amazon.Pay.bindChangeAction('#changeButton1', {
    amazonCheckoutSessionId: 'xxxx',
    changeAction: 'changeAddress'
  });
</script>

Changing payment instrument:

<script type="text/javascript" charset="utf-8">
  amazon.Pay.bindChangeAction('#changeButton2', {
    amazonCheckoutSessionId: 'xxxx',
    changeAction: 'changePayment'
  });
</script>

Function parameters

Note: Both changeAction values will trigger the same buyer experience. Regardless of which value you specify, the buyer will be given the option of updating both their shipping address and payment method. Eventually, the changeAction value will trigger the expected behavior.

Parameter	Description
amazonCheckoutSessionId (required) Type: string	Amazon Pay Checkout Session identifier
changeAction (required) Type: string	Update requested by the buyer Supported values: 'changeAddress', 'changePayment'