Set payment info

[Step 4 of 9] In this step, you will set the order total and any other transaction metadata. At the end of this step, you will be able to redirect the buyer to a unique amazonPayRedirectUrl for transaction processing.


1. Set payment info

Call Update Checkout Session to set transaction metadata. Note that you can only set payment info, while the Checkout Session object is in an Open state and before the buyer is redirected to the Amazon Pay Payments Processing page.

Use the checkoutResultReturnUrl parameter to specify the URL the buyer is redirected to after the Amazon Pay Payments Processing page.

Request

curl "https://pay-api.amazon.com/:version/checkoutSessions/:checkoutSessionId" \
-X PATCH
-H "x-amz-pay-authorization: Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-d @request_body

Request body

{
    "webCheckoutDetails": {
        "checkoutResultReturnUrl":"https://a.com/merchant-confirm-page"
    },
    "paymentDetails": {
        "paymentIntent":"Confirm",
        "totalOrderAmount": {
            "amount":"1",
            "currencyCode":"USD"
        },
        "chargeAmount": {
            "amount":"1",
            "currencyCode":"GBP"
        }
    },
    "merchantMetadata": {
        "merchantReferenceId":"Merchant reference ID",
        "merchantStoreName":"Merchant store name",
        "noteToBuyer":"Note to buyer",
        "customInformation":"Custom information"
    },
    "platformId":"SPId"
}

Request parameters

Name
Location
Description
checkoutSessionId
(required)

Type: string
Path parameter
Checkout Session identifier
webCheckoutDetails

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

Modifiable: Multiple times before the buyer is redirected to the AmazonPayReturnUrl.
paymentDetails

Type: paymentDetails
Body
Payment details specified by the merchant. If you are integrating with an acquirer, please always set the PaymentIntent value to "Confirm".

Note: Pass totalOrderAmount to make sure buyer facing communication about the amount of the order is correct. Use chargeAmount to specify how much are you going to charge on order placement, calling the acquirer API.

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
providerMetadata

Type: providerMetadata
Body
Transaction identifier created by the Payment Service Provider (PSP).

Only PSPs should use these fields.

Modifiable: Multiple times before the buyer is redirected to the AmazonPayReturnUrl.

Response

{
    "checkoutSessionId":"ada3f397-7d4b-4a55-abac-786685c02d8b",
    "webCheckoutDetails": {
        "checkoutReviewReturnUrl":"https://a.com/merchant-review-page",
        "checkoutResultReturnUrl":"https://a.com/merchant-confirm-page",
        "amazonPayRedirectUrl":"https://pay.amazon.com/redirect/checkoutId-1"
    },
    "productType":"PayAndShip",
    "paymentDetails": {
        "paymentIntent":"Confirm",
        "totalOrderAmount": {
            "amount":"1",
            "currencyCode":"USD"
        },
        "chargeAmount": {
            "amount":"1",
            "currencyCode":"USD"
        }
    },
    "merchantMetadata": {
        "merchantReferenceId":"Merchant reference ID",
        "merchantStoreName":"Merchant store name",
        "noteToBuyer":"Note to buyer",
        "customInformation":"Custom information"
    },
    "supplementaryData":null, // Amazon Pay system data 
    "buyer": {
        "buyerId":"amzn1.account.AH34VHFHHYL4YMBuyerId",
        "name":"name-1",
        "email":"name@amazon.com"
    },
    "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"
    }
    "paymentPreferences": [
        {
            "paymentDescriptor":"Visa ****1111 (Amazon Pay)"
            
        }
    ],
    "statusDetails": {
        "state":"Open",
        "reasonCode":null,
        "reasonDescription":null,
        "lastUpdatedTimestamp":"20191015T195703Z"
    },
    "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":"AEMGQX8TKDO54",
    "chargePermissionId":null,
    "chargeId":null,
    "constraints": [],
    "creationTimestamp":"20191015T195655Z",
    "expirationTimestamp":"20191016T195655Z",
    "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
    },
    "releaseEnvironment":"Sandbox",
    "amazonPayToken": null    // Provided only after buyer returns from amazonPayRedirectUrl
}

2. Redirect to AmazonPayRedirectUrl

Update Checkout Session response will include a Constraint object, until all mandatory parameters are provided. The mandatory parameters are:

  • checkoutResultReturnUrl
  • paymentIntent
  • totalOrderAmount

Once there are no constraints, the response will return a unique amazonPayRedirectUrl. Redirect the buyer to that URL to complete checkout.