Display shipping and payment info

[Step 3 of 8] After the buyer selects their preferred shipping address and payment instrument, they are redirected to the checkoutReviewReturnUrl , which is specified on the Checkout Session. The Amazon Pay checkout session ID will be included as a query parameter. Use the checkout session ID to get checkout info (such as shipping address and payment instrument) and to enable updates after the buyer returns to your site.


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.

Request

curl "https://pay-api.amazon.com/:environment/:version/checkoutSessions/:checkoutSessionId"
-X GET
-H "x-amz-pay-authorization: Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"

Request parameters

Name
Location
Description
CheckoutSessionId
(required)

Type: string
Path Parameter
Checkout session identifier

Response

{
    "checkoutSessionId": "bd504926-f659-4ad7-a1a9-9a747aaf5275",
    "webCheckoutDetail": {
        "checkoutReviewReturnUrl": "https://a.com/merchant-review-page",
        "checkoutResultReturnUrl": null,
        "amazonPayRedirectUrl": null
    },
    "productType": "PayAndShip",
    "paymentDetail": {
        "paymentIntent": null,
        "canHandlePendingAuthorization": false,
        "chargeAmount": null,
        "softDescriptor": null,
        "presentmentCurrency": "USD"
    },
    "merchantMetadata": {
        "merchantReferenceId": null,
        "merchantStoreName": null,
        "noteToBuyer": null,
        "customInformation": null
    },
    "supplementaryData":null, // Amazon Pay system data
    "buyer": {
        "buyerId": "amzn1.account.AH34VHFHHYL4YMBuyerId",
        "name": "name-1",
        "email": "name@amazon.com"
    },
    "paymentPreferences": [
        {
            "paymentDescriptor": "Visa ****1111 (Amazon Pay)",
            "billingAddress":{ // Only available in EU or for PayOnly product type
                "name": "Work",
                "addressLine1": "440 Terry Ave",
                "addressLine2": "",
                "addressLine3": "",
                "city": "Seattle",
                "county": "King",    
                "district": "Seattle",
                "stateOrRegion": "WA",
                "postalCode": "98121",
                "countryCode": "US"
            }
        }
    ],
    "statusDetail": {
        "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

Parameter
Description
amazonCheckoutSessionId
(required)

Type: string
Amazon Pay Checkout Session identifier
changeAction
(required)

Type: string
Update requested by the buyer

Supported values: 'changeAddress', 'changePayment'