Se connecter

Merci de votre visite. Cette page est disponible en anglais uniquement.

Checkout Session

A Checkout Session represents a single active session (or engagement) for a buyer on your website. The Checkout Session can be used to facilitate a one-time charge, multiple charges, or recovery from a declined payment.

The Checkout Session starts in the Open state. In the Open state, you can use the Checkout Session to retrieve checkout details such as shipping address, and set relevant payment details such as total order amount. You can also use the Checkout Session to either charge the buyer immediately, or exchange it for a Charge Permission that can be used to charge the buyer later.

The Checkout Session moves to the Completed state after you call Complete Checkout Session if transaction processing was successful. In the Completed state, you can use the Checkout Session to retrieve references to a Charge Permission and also a Charge if payment authorization was requested.

The Checkout Session moves to the Canceled state after the Checkout Session has been in the Open state for 24 hours or if transaction processing failed. In the Canceled state, you can use the Checkout Session to retrieve why checkout failed.

Note that Amazon Pay permanently deletes Checkout Session objects and any associated information after 30 days.

Supported operations:

Checkout Session object
States and reason codes
Create Checkout Session
Get Checkout Session
Update Checkout Session
Complete Checkout Session
Related topics

Checkout Session object

Parameter	Description
checkoutSessionId Type: string	Checkout Session identifier
chargePermissionType Type: string	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"
recurringMetadata Type: recurringMetadata	Metadata about how the recurring Charge Permission will be used. Amazon Pay only uses this information to calculate the Charge Permission expiration date and in buyer communication Note that it is still your responsibility to call Create Charge to charge the buyer for each billing cycle
webCheckoutDetails Type: webCheckoutDetails	URLs associated to the Checkout Session used for completing checkout
productType Type: string	Amazon Pay integration type. You can not set this value via Checkout Session operations, you must set it using button `productType` parameter
paymentDetails Type: paymentDetails	Payment details specified by the merchant, such as the amount and method for charging the buyer
merchantMetadata Type: merchantMetadata	Merchant-provided order details
paymentMethodOnFileMetadata Type: paymentMethodOnFileMetadata	Metadata about how the Saved Wallet charge permission will be used.
platformId Type: string	Merchant identifier of the Solution Provider (SP)- also known as ecommerce provider Only SPs should use this field
providerMetadata Type: providerMetadata	Payment service provider (PSP)-provided order information Only PSPs should use these fields
buyer Type: buyer	Details about the buyer, such as their unique identifier, name, and email This info will only be returned for a Checkout Session in the Open state
shippingAddress Type: address	Shipping address selected by the buyer
billingAddress Type: address	Billing address for buyer-selected payment instrument
paymentPreferences Type: list<paymentPreferences>	List of payment instruments selected by the buyer
statusDetails Type: statusDetails	State of the Checkout Session object
constraints Type: list<constraint>	Constraints that must be addressed to complete Amazon Pay checkout
creationTimestamp Type: dateTime	Universal Time Coordinated (UTC) date and time when the Checkout Session was created in ISO 8601 format
expirationTimestamp Type: dateTime	UTC date and time when the Checkout Session will expire in ISO 8601 format
chargePermissionId Type: string	Charge permission identifier returned after Checkout Session is complete Used for creating charges for deferred transactions
chargeId Type: string	Charge identifier returned after Checkout Session is complete Used for processing refunds
storeId Type: string	Amazon Pay store ID. Retrieve this value from Amazon Pay Integration Central: US, EU, JP
deliverySpecifications Type: deliverySpecifications	Specify shipping restrictions to prevent buyers from selecting unsupported addresses from their Amazon address book
releaseEnvironment Type: string	The environment the Checkout Session object was created in (either Sandbox or Live)
supplementaryData Type: string	Data enrichment field. Do not use

Type: webCheckoutDetails

Parameter	Description
checkoutReviewReturnUrl Type: string	Checkout review URL provided by the merchant. Amazon Pay will redirect to this URL after the buyer selects their preferred payment instrument and shipping address Note: In the Live environment, URLs must use HTTPS protocol. The URL domain must be added to Seller Central. See Add domains to Seller Central for more information. In Sandbox environment, you don't need a SSL certificate and can use the HTTP protocol if you're testing on localhost (http://localhost). You don't need to add URLs to the JavaScript Origins in SellerCentral Max length: 1024 characters/bytes
checkoutResultReturnUrl Type: string	Checkout result URL provided by the merchant. Amazon Pay will redirect to this URL after completing the transaction Note: In the Live environment, URLs must use HTTPS protocol. In Sandbox environment, you don't need a SSL certificate and can use the HTTP protocol if you're testing on localhost (http://localhost) Max length: 1024 characters/bytes
checkoutCancelUrl Type: string	Checkout cancellation URL provided by the merchant. Amazon Pay will redirect to this URL if the buyer cancels checkout on any Amazon Pay hosted page If you do not provide a `checkoutCancelUrl`, Amazon Pay will redirect the buyer using the following logic: Payment and address selection hosted page - redirect to referrer URL unless it's a different domain than `checkoutReviewReturnUrl`. If there is a domain mismatch the buyer will be redirected to `checkoutReviewReturnUrl` Update payment and address hosted page - redirect to `checkoutReviewReturnUrl` Declined payment handling hosted page - redirect to `checkoutResultReturnUrl` Max length: 1024 characters/bytes
amazonPayRedirectUrl Type: string	URL provided by Amazon Pay. Merchant will redirect to this page after setting transaction details to complete checkout Max length: 256 characters/bytes
checkoutMode Type: string	Specify whether the buyer will return to your website to review their order before completing checkout Supported values: 'ProcessOrder' - Buyer will complete checkout on the Amazon Pay hosted page immediately after clicking on the Amazon Pay button. `paymentDetails` is required when using 'ProcessOrder'. `addressDetails` is also required if you use 'ProcessOrder' with `productType` set to 'PayAndShip'

Type: deliverySpecifications

Parameter	Description
specialRestrictions Type: list<string>	Rule-based restrictions Note: Amazon will only validate this value in Sandbox. This parameter is ignored in the Live environment if an unsupported value is used Supported values: 'RestrictPOBoxes' - Marks PO box addresses in US, CA, GB, FR, DE, ES, PT, IT, AU as restricted 'RestrictPackstations' - Marks packstation addresses in DE as restricted
addressRestrictions Type: addressRestrictions	Country-based restrictions

Type: addressRestrictions

Parameter	Description
type Type: string	Specifies whether addresses that match restrictions configuration should or should not be restricted Note: Amazon will only validate this value in Sandbox. This parameter is ignored in the Live environment if an unsupported value is used Supported values: 'Allowed' - Mark addresses that don't match restrictions configuration as restricted 'NotAllowed' - Mark addresses that match restrictions configuration as restricted
restrictions Type: hash<countryCode:restriction>	Hash of country-level restrictions that determine which addresses should or should not be restricted based on `addressRestrictions.type` parameter. CountryCode is a string that represents the country code of the address in ISO 3166 format. Amazon will only validate CountryCode in Sandbox. CountryCode is ignored in the Live environment if an unsupported value is used

Type: recurringMetadata

Parameter	Description
frequency Type: frequency	Frequency at which the buyer will be charged using a recurring Charge Permission. You should specify a frequency even if you expect ad hoc charges Possible combinations: Year: 1-3 Month: 1-36 Week: 1-57 Day: 1-1095
amount Type: price	Amount the buyer will be charged for each recurring cycle. Set to null if amount varies

Type: frequency

Parameter	Description
unit Type: string	Frequency unit for each billing cycle. For multiple subscriptions, specify the frequency unit for the shortest billing cycle. Only use Variable if you charge the buyer on an irregular cadence, see handling variable cadence for more info Supported values: 'Year', 'Month', 'Week', 'Day', 'Variable'
value Type: string	Number of frequency units per billing cycle. For example, to specify a weekly cycle set `unit` to Week and `value` to 1. You must set `value` to 0 if you're using variable `unit`

Type: restriction

Parameter	Description
statesOrRegions Type: list<string>	List of country-specific states that should or should not be restricted based on `addressRestrictions.type` parameter Note: US addresses - Use 2-character state codes (for example: WA, CA, IL) All other countries - This element is free text. Include all applicable variants: 2-character code, fully spelled out, and abbreviated
zipCodes Type: list<string>	List of country-specific zip codes that should or should not be restricted based on `addressRestrictions.type` parameter Use wild card symbols to skip over variable alphanumeric characters. The "*" symbol will match multiple characters. The "?" symbol will only match a single character

Type: paymentDetails

Parameter	Description
paymentIntent Type: string	Payment flow for charging the buyer Supported values: 'Confirm' - Create a Charge Permission to authorize and capture funds at a later time 'Authorize' - Authorize funds immediately and capture at a later time 'AuthorizeWithCapture' - Authorize and capture funds immediately. If you use this `paymentIntent` you can't set `canHandlePendingAuthorization` to true
canHandlePendingAuthorization Type: boolean	Boolean that indicates whether merchant can handle pending response If set to true: One-time checkout: Dynamic authorization is enabled. The Charge will either be in an "Authorized", "Declined", or "AuthorizationInitiated" state. If the Charge is in an "AuthorizationInitiated" state, Amazon Pay will process the authorization asynchronously and you will receive authorization results within 24 hours. See asynchronous processing and Charge states for more info Recurring checkout: Amazon Pay will process the authorization asynchronously and you will receive authorization results within 24 hours. See asynchronous processing for more info
chargeAmount Type: price	Amount to be processed using `paymentIntent` during checkout
totalOrderAmount Type: price	The total order amount. Only use if you need to split the order to capture additional payment after checkout is complete
presentmentCurrency Type: string	The currency that the buyer will be charged in ISO 4217 format. Example: USD See multi-currency integration for more info
softDescriptor Type: string	Description shown on the buyer payment instrument statement. You can only use this parameter if `paymentIntent` is set to AuthorizeWithCapture Do not store sensitive data about the buyer or the transaction in this field. Sensitive data includes, but is not limited to: government-issued identification, bank account numbers, or credit card numbers The soft descriptor sent to the payment processor is: "AMZ* <soft descriptor specified here>" Default: "AMZ*<SELLER_NAME> pay.amazon.com" Max length: 16 characters/bytes
allowOvercharge Type: boolean	Only applicable if you registered in JP marketplace. This parameter will always return as null for all other regions
extendExpiration Type: boolean	Only applicable if you registered in JP marketplace. This parameter will always return as null for all other regions

Type: price

Parameter	Description
amount Type: string	Transaction amount
currencyCode Type: string	Transaction currency code in ISO 4217 format Example: USD

Type: providerMetadata

Parameter	Description
providerReferenceId Type: string	Payment service provider (PSP)-provided order identifier Only PSPs should use these fields

Type: merchantMetadata

Parameter	Description
merchantReferenceId Type: string	External merchant order identifier. The merchant order identifier is shared in buyer communication and in the buyer transaction history on the Amazon Pay website Max length: 256 characters/bytes
merchantStoreName Type: string	Merchant store name. Setting this parameter will override the default value configured in Seller Central (US, EU, JP). The store name is shared in buyer communication and in the buyer transaction history on the Amazon Pay website Max length: 50 characters/bytes
noteToBuyer Type: string	Description of the order that is shared in buyer communication Do not store sensitive data about the buyer or the transaction in this field. Sensitive data includes, but is not limited to: government-issued identification, bank account numbers, or credit card numbers Max length: 255 characters/bytes
customInformation Type: string	Custom info for the order. This data is not shared in any buyer communication Do not store sensitive data about the buyer or the transaction in this field. Sensitive data includes, but is not limited to: government-issued identification, bank account numbers, or credit card numbers Max length: 4096 characters/bytes

Type: paymentMethodOnFileMetadata

Parameter

Description

setupOnly

Type: boolean

Represents if merchant wants to trigger only setup flow to setup Saved Wallet.
> true - will present setup intent page to the buyers. Additionally if a chargePermissionId is also passed in the payload json, setting this value to true, will trigger a update payment method or address flow for a Saved Wallet charge permission id.
> false - will present payment method of file setup with a purchase to the buyers.

Default: null

Type: buyer

Parameter	Description
buyerId Type: string	Unique Amazon Pay buyer identifier Max length: 42 characters/bytes
name Type: string	Buyer name Max length: 50 characters/bytes
email Type: string	Buyer email address Max length: 64 characters/bytes
phoneNumber Type: string	Buyer default billing address phone number Max length: 20 characters/bytes
primeMembershipTypes Type: list<primeMembershipType>	List of buyer Prime memberships. This data is not available for general use

Type: paymentPreferences

Parameter	Description
paymentDescriptor Type: string	Amazon Pay-provided description for buyer-selected payment instrument Max length: 64 characters/bytes

Type: address

Parameter	Description
name Type: string	Address name Max length: 50 characters/bytes
addressLine1 Type: string	The first line of the address Max length: 180 characters/bytes
addressLine2 Type: string	The second line of the address Max length: 60 characters/bytes
addressLine3 Type: string	The third line of the address Max length: 60 characters/bytes
city Type: string	City of the address Max length: 50 characters/bytes
county Type: string	County of the address Max length: 50 characters/bytes
district Type: string	District of the address Max length: 50 characters/bytes
stateOrRegion Type: string	The state or region: US and CA addresses - Response will always be a 2-character code All other countries - This element is free text and can be either a 2-character code, fully spelled out, or abbreviated Max length: 50 characters/bytes
postalCode Type: string	Postal code of the address Max length: 20 characters/bytes
countryCode Type: string	Country code of the address in ISO 3166 format Max length: 3 characters/bytes
phoneNumber Type: string	Phone number Max length: 20 characters/bytes

Type: addressDetails

Required parameters based on region. See address formatting and validation for more info.

Parameter	Description
name Type: string	Address name Max length: 50 characters/bytes
addressLine1 Type: string	The first line of the address Max length: 60 characters/bytes
addressLine2 Type: string	The second line of the address Max length: 60 characters/bytes
addressLine3 Type: string	The third line of the address Max length: 60 characters/bytes
city Type: string	City of the address Max length: 50 characters/bytes
districtOrCounty Type: string	District or county of the address Max length: 50 characters/bytes
stateOrRegion Type: string	The state or region of the address Max length: 50 characters/bytes
postalCode Type: string	Postal code of the address Max length: 20 characters/bytes
countryCode Type: string	Country code of the address in ISO 3166 format Max length: 2 characters/bytes
phoneNumber Type: string	Phone number Max length: 20 characters/bytes

Type: statusDetails

Parameter	Description
state Type: string	Current object state
reasonCode Type: string	Reason code for current state
reasonDescription Type: string	An optional description of the Checkout Session state
lastUpdatedTimestamp Type: dateTime	UTC date and time when the state was last updated in ISO 8601 format

Type: constraint

Parameter	Description
constraintId Type: string	Code for any Checkout Session constraint
description Type: string	Description of the Checkout Session constraint

Constraint Code	Description
CheckoutResultReturnUrlNotSet	`checkoutResultReturnURL` has not been set on the Checkout Session
ChargeAmountNotSet	`chargeAmount` has not been set on the Checkout Session
PaymentIntentNotSet	`paymentIntent` has not been set on the Checkout Session
BuyerNotAssociated	Buyer-preferred payment instrument or shipping address has not been set on the Checkout Session
RecurringFrequencyNotSet	`frequency` has not been set on the Checkout Session. Only applicable if you're requesting a recurring Charge Permission

States and reason codes

State	Description	Reason code
Open	The initial Checkout Session state. Checkout Session state will return missing value constraints, until mandatory fields are provided by the merchant using Update Checkout Session. After all constraints have been removed, the merchant will redirect the buyer to the AmazonPayRedirectUrl to complete checkout. The Checkout Session state will then move to either Completed or Canceled state Note that the Checkout Session will move to Canceled state if the buyer doesn't complete checkout within 24 hours Allowed operation(s): GET Checkout Session UPDATE Checkout Session COMPLETE Checkout Session	-
Completed	Checkout was successfully completed. The buyer was redirected to the `AmazonPayRedirectUrl` and checkout was confirmed with Complete Checkout Session. The payment intent was finalized. The Checkout Session can no longer be used to perform another payment, or retry a charge Note: if you set `canHandlePendingAuthorization` to true, the Checkout Session state will be in a Completed state after checkout is confirmed with Complete Checkout Session even though the Authorization might later fail. See asynchronous processing for more info Allowed operation(s): GET Checkout Session (will return Charge Permission ID, Charge ID, and other Checkout Session details) COMPLETE Checkout Session	-
Canceled	Checkout was not successfully completed due to buyer abandoment, payment decline, or because checkout wasn't confirmed with Complete Checkout Session. The payment intent was not finalized Allowed operation(s): GET CheckoutSession (will only return state and reasonCode)	BuyerCanceled - The buyer canceled the checkout by clicking the Return to previous page button Expired - The Checkout Session expired 24 hour after creation because there was no redirect to the amazonPayRedirectUrl, buyer did not complete payment, or the checkout was not confirmed with Complete Checkout Session AmazonCanceled - Amazon has canceled the transaction due to service unavailability. This is not a payment associated cancelation Declined - Generic payment decline reason code that includes fraud declines, failure to complete multi-factor authentication (MFA) challenge, and issues with the payment instrument

Operations

Create Checkout Session

Create a new Amazon Pay Checkout Session to customize and manage the buyer experience, from when the buyer clicks the Amazon Pay button to when they complete checkout.

Request


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

-X POST

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

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

-H "x-amz-pay-idempotency-key:AVLo5tI10BHgEk2jEXAMPLEKEY"

-d @request_body


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

-X POST

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

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

-H "x-amz-pay-idempotency-key:AVLo5tI10BHgEk2jEXAMPLEKEY"

-d @request_body

Request body

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

Request parameters

Name	Location	Description
x-amz-pay-idempotency-key (required) Type: string	Header	Idempotency key to safely retry requests
webCheckoutDetails (required) 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
storeId (required) Type: string	Body	Amazon Pay store ID. Retrieve this value from Amazon Pay Integration Central: US, EU, JP
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"
recurringMetadata Type: recurringMetadata	Body	Metadata about how the recurring Charge Permission will be used. Amazon Pay only uses this information to calculate the Charge Permission expiration date and in buyer communication Note that it is still your responsibility to call Create Charge to charge the buyer for each billing cycle
paymentMethodOnFileMetadata Type: paymentMethodOnFileMetadata	Body	Metadata about how payment method on file charge permission will be used.
deliverySpecifications Type: deliverySpecifications	Body	Specify shipping restrictions and limit which addresses your buyer can select from their Amazon address book
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`
platformId Type: string	Body	Merchant identifier of the Solution Provider (SP). Only SPs should use this field. Modifiable: Multiple times before the buyer is redirected to the `amazonPayReturnUrl`.
providerMetadata Type: providerMetadata	Body	Payment service provider (PSP)-provided order details Only PSPs should use these fields
addressDetails Type: addressDetail	Body	Buyer provided shipping address. Only use this parameter if `checkoutMode` is ProcessOrder and `productType` is PayAndShip

Response

Returns HTTP 201 status response code if the operation was successful. Subsequent retry attempts using the same Idempotency Key may return a HTTP 200 status response code if a new resource is not created.

{
    "checkoutSessionId": "bd504926-f659-4ad7-a1a9-9a747aaf5275",
    "webCheckoutDetails": {
        "checkoutReviewReturnUrl": "https://a.com/merchant-review-page",
        "checkoutResultReturnUrl": null,
        "checkoutCancelUrl": null,
        "amazonPayRedirectUrl": null
    },
    "productType": "PayAndShip",
    "chargePermissionType": "Recurring",   
    "recurringMetadata": {
        "frequency": { 
            "unit": "Month", 
            "value": "1" 
        },
        "amount": { 
            "amount": "30",
            "currencyCode": "USD"
        }
    }, 
    "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
    },
    "paymentMethodOnFileMetadata": null,
    "supplementaryData": null, // Amazon Pay system data
    "buyer": null,
    "billingAddress": null,
    "paymentPreferences": [
        null
    ],
    "statusDetails": {
        "state": "Open",
        "reasonCode": null,
        "reasonDescription": null,
        "lastUpdatedTimestamp": "20191015T204327Z"
    },
    "shippingAddress": null,  // Null for PayOnly product type
    "platformId": null,
    "chargePermissionId": null,
    "chargeId": null,
    "constraints": [
        {
           "constraintId": "BuyerNotAssociated",
            "description": "There is no buyer associated with the Checkout Session. Return the checkout session id to the Amazon Pay Button to allow buyer to login."
        },
        {
           "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
    },
    "releaseEnvironment": "Sandbox"
}

Error codes

HTTP status code	Reason code	Description
400 BAD_REQUEST	CurrencyMismatch	The `chargeAmount` currency code provided in the request does not match the `presentmentCurrency` currency code

Generic errors can be found here.

Get Checkout Session

Get Checkout Session details includes buyer info, payment instrument details, and shipping address. Shipping address will only be returned if Checkout Session has PayAndShip product type. Use this operation to determine if checkout was successful after the buyer returns from the AmazonPayRedirectUrl to the specified checkoutResultReturnUrl.

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

Response

Returns HTTP 200 status response code if the operation was successful.

{
    "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
    },
    "paymentMethodOnFileMetadata": 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
    },
    "releaseEnvironment": "Sandbox"
}

Error codes

HTTP status code	Reason code	Description
404 NOT_FOUND	ResourceNotFound	Checkout Session details are permanently deleted after 30 days. Any request on the Checkout Session will return this error code

Generic errors can be found here.

Update Checkout Session

Update the Checkout Session with transaction details. You can keep updating the Checkout Session until the buyer is redirected to amazonPayRedirectUrl. Once all mandatory parameters have been set, the Checkout Session object will respond with an unique amazonPayRedirectUrl that you will use to redirect the buyer to complete checkout.

Set chargeAmount to the value that should be processed using the paymentIntent during checkout. If you need to split the order to capture additional payment after checkout is complete, use the optional totalOrderAmount parameter to set the full order amount.

Request


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

-X PATCH

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

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

-d @request_body


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

-X PATCH

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

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

-d @request_body

Request body

{
    "webCheckoutDetails": {
        "checkoutResultReturnUrl": "https://a.com/merchant-confirm-page"
    },
    "paymentDetails": {
        "paymentIntent": "AuthorizeWithCapture",
        "canHandlePendingAuthorization":false,
        "softDescriptor": "Descriptor",
        "chargeAmount": {
            "amount": "1",
            "currencyCode": "USD"
        }
     },
    "merchantMetadata": {
        "merchantReferenceId": "Merchant reference ID",
        "merchantStoreName": "Merchant store name",
        "noteToBuyer": "Note to buyer",
        "customInformation": "Custom information"
    }
}

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
recurringMetadata Type: recurringMetadata	Body	Metadata about how the recurring Charge Permission will be used. Amazon Pay only uses this information to calculate the Charge Permission expiration date and in buyer communication Note that it is still your responsibility to call Create Charge to charge the buyer for each billing cycle
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`
platformId Type: string	Body	Merchant identifier of the Solution Provider (SP). Only SPs should use this field. 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

Returns HTTP 200 status response code if the operation was successful.

{
    "checkoutSessionId": "ada3f397-7d4b-4a55-abac-786685c02d8b",
    "webCheckoutDetails": {
        "checkoutReviewReturnUrl": "https://a.com/merchant-review-page",
        "checkoutResultReturnUrl": "https://a.com/merchant-confirm-page",
        "checkoutCancelUrl": null,
        "amazonPayRedirectUrl": "https://pay.amazon.com/redirect/checkoutId-1"
    },
    "productType": "PayAndShip",
    "paymentDetails": {
        "paymentIntent": "AuthorizeWithCapture",
        "canHandlePendingAuthorization": false,
        "chargeAmount": {
            "amount": "1",
            "currencyCode": "USD"
        },
        "totalOrderAmount": null,
        "softDescriptor": "Descriptor",
        "presentmentCurrency": "USD",
        "allowOvercharge": null,
        "extendExpiration": null
    },
    "merchantMetadata": {
        "merchantReferenceId": "Merchant reference ID",
        "merchantStoreName": "Merchant store name",
        "noteToBuyer": "Note to buyer",
        "customInformation": "Custom information"
    },
    "paymentMethodOnFileMetadata": 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": "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": null,
    "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"
}

Error codes

HTTP status code	Reason code	Description
404 NOT_FOUND	ResourceNotFound	Checkout Session details are permanently deleted after 30 days. Any request on the Checkout Session will return this error code
422 UNPROCESSABLE_ENTITY	InvalidCheckoutSessionStatus	You tried to call an operation on a Checkout Session that is in a state where that operation is not allowed

Generic errors can be found here.

Complete Checkout Session

Complete Checkout Session after the buyer returns to checkoutResultReturnUrl to confirm that the buyer has successfully returned to your site.

This request returns HTTP 200 status response code if the paymentIntent was successful or a 4xx/5xx response if paymentIntent failed.

Request


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

-X POST

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

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

-d @request_body


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

-X POST

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

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

-H "x-amz-pay-idempotency-key:AVLo5tI10BHgEk2jEXAMPLEKEY"

-d @request_body

Request body

{
    "chargeAmount": {
        "amount": "14.00",
        "currencyCode": "USD"
    }
}

Request parameters

Name	Location	Description
checkoutSessionId (required) Type: string	Path parameter	Checkout Session identifier
chargeAmount (required) Type: price	Body	Amount to be processed using `paymentIntent` during checkout. Must match Checkout Session object `paymentDetails.chargeAmount`
totalOrderAmount Type: price	Body	Total order amount. Must match Checkout Session object `paymentDetails.totalOrderAmount` if a value was provided

Response

Returns HTTP 200 status response code if paymentIntent was successful.

{
    "checkoutSessionId": "bd504926-f659-4ad7-a1a9-9a747aaf5275",
    "webCheckoutDetails": null,
    "chargePermissionType": PaymentMethodOnFile,   
    "recurringMetadata": null,
    "productType": null,
    "paymentDetails": null,
    "merchantMetadata": null,
    "paymentMethodOnFileMetadata": null,    
    "supplementaryData":null, // Amazon Pay system data 
    "buyer": null,
    "billingAddress": null,
    "paymentPreferences": [
        null
    ],
    "statusDetails": {
        "state": "Completed",
        "reasonCode": null,
        "reasonDescription": null,
        "lastUpdatedTimestamp": "20191015T204327Z"
    },
    "shippingAddress": null,
    "platformId":null,
    "chargePermissionId": "S01-5105180-3221187",
    "chargeId": "S01-5105180-3221187-C056351",
    "constraints": [
        null
    ],
    "creationTimestamp": "20191015T204313Z",
    "expirationTimestamp": null,
    "storeId": null,
    "deliverySpecifications": null,
    "providerMetadata": null,
    "releaseEnvironment": null
}

Error codes

HTTP status code	Reason code	Description
400 BAD_REQUEST	CurrencyMismatch	The currency code provided in the request does not match the currency set during checkout
400 BAD_REQUEST	TransactionAmountExceeded	You've exceeded the maximum charge amount allowed for the Checkout Session
404 NOT_FOUND	ResourceNotFound	Checkout Session details are permanently deleted after 30 days. Any request on the Checkout Session will return this error code
409 CONFLICT	AmountMismatch	Mismatch between Checkout Session object `chargeAmount` and the request `chargeAmount`
422 UNPROCESSABLE_ENTITY	CheckoutSessionCanceled	Checkout was unsuccessful because the buyer cancelled the transaction or payment was declined
422 UNPROCESSABLE_ENTITY	InvalidCheckoutSessionStatus	You tried to call an operation on a Checkout Session that is in a state where that operation is not allowed
422 UNPROCESSABLE_ENTITY	InvalidChargeStatus	You tried to call an operation on a Charge that is in a state where that operation is not allowed or you tried to Complete Checkout Session on a Checkout Session with `paymentIntent` set to AuthorizeWithCapture and `canHandlePendingAuthorization` set to true
422 UNPROCESSABLE_ENTITY	HardDeclined	Charge was hard declined. Retry attemps will not succeed. Please contact the buyer and have them choose a different payment instrument
422 UNPROCESSABLE_ENTITY	PaymentMethodNotAllowed	The payment method selected by the buyer is not allowed for this charge
422 UNPROCESSABLE_ENTITY	AmazonRejected	Charge was declined by Amazon. The associated Charge Permission will also be canceled
422 UNPROCESSABLE_ENTITY	MFANotCompleted	Multi-factor authentication (MFA) is required to be complete by the buyer for this transaction to process
422 UNPROCESSABLE_ENTITY	TransactionTimedOut	If you set `canHandlePendingAuthorization` to false, the Charge was declined because Amazon Pay did not have enough time to process the authorization. Contact the buyer and have them choose another payment method. If you frequently encounter this decline, consider setting `canHandlePendingAuthorization` to true If you set `canHandlePendingAuthorization` to true, the Charge was declined because Amazon Pay was unable to determine the validity of the order. Contact the buyer and have them choose another payment method. See asynchronous processing for more information
500 INTERNAL_SERVER_ERROR	ProcessingFailure	Amazon could not process the Charge because of an internal processing error. You should retry the charge only if the Charge Permission is in the Chargeable state

Generic errors can be found here.

Checkout Session

Checkout Session object

Type: webCheckoutDetails

Type: deliverySpecifications

Type: addressRestrictions

Type: recurringMetadata

Type: frequency

Type: restriction

Type: paymentDetails

Type: price

Type: providerMetadata

Type: merchantMetadata

Type: paymentMethodOnFileMetadata

Type: buyer

Type: paymentPreferences

Type: address

Type: addressDetails

Type: statusDetails

Type: constraint

States and reason codes

Operations

Create Checkout Session

Request

Request body

Request parameters

Response

Error codes

Get Checkout Session

Request

Request parameters

Response

Error codes

Update Checkout Session

Request

Request body

Request parameters

Response

Error codes

Complete Checkout Session

Request

Request body

Request parameters

Response

Error codes

Related topics