This is a draft guide. Content is subject to change.

API introduction


Objects

There are 2 primary objects that you can use to complete your payments with Amazon Pay and your acquirer: CheckoutSession and ChargePermission. Each represents a distinct payment operation or agreement, and each has different periods of relevance and use.

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 new, one-time charge, or recovery from a declined payment. Create a new Checkout Session each time you engage the buyer.

The Checkout Session starts in an Open state and moves to a Canceled state, unless the buyer completes checkout within 24 hours. In the Open state, you can use the Checkout Session to retrieve checkout details such as buyer profile, shipping address, and payment information.

After the buyer returns from the Amazon Pay Payment Processing page, you will be able to use the Checkout Session object, still in Open state, to process payment with your acquirer. The Checkout Session will stay in status Open after the buyer completes checkout and you process payment with the acquirer.

Note that Amazon Pay permanently deletes Checkout Session objects and any associated information after 30 days. After expiration the Checkout Session will move to status Canceled.

Charge Permission

A Charge Permission is a relationship between you (the merchant) and the buyer. It represents the buyer consent to be charged. The Charge Permission is used to facilitate deferred transactions. For simple payment use cases, such as immediate Authorization and Capture, you may not need to use the Charge Permission object at all.

You can also use the Charge Permission to retrieve the relevant checkout details needed to complete the order such as buyer name, buyer email, and order shipping address. Note that you can only retrieve checkout details for 30 days after the time that the Charge Permission was created. A Charge Permission is created as the buyer returns from the Amazon Pay Payment Processing page, and the relevant Charge Permission ID is provided as part of the Get Checkout Session response.

A Charge Permission can be used to retrieve buyer details after checkout is completed, and it expires after 180 days from it's creation.


API basics

Endpoint

https://pay-api.amazon.com/:environment/:version
https://pay-api.amazon.eu/:environment/:version
https://pay-api.amazon.jp/:environment/:version
URL parameter
Description
environment
Amazon Pay environment

Possible values: "sandbox" or "live"
version
Amazon Pay API version

Possible values: "v1"

Headers

At a minimum, you must set the x-amz-pay-date, content-type, and authorization headers on every request you make to Amazon Pay. Additionally, you must set the x-amz-pay-idempotency-key header for all POST requests.

Header key
Description
x-amz-pay-date
UTC timestamp of when the request is made in ISO 8601 format. This header is required for every request

Example: "20190805T051457Z"
x-amz-pay-idempotency-key
The idempotency key header is used to safely retry requests. See Idempotency key for more information. This header is required for POST requests

Example: "LfOgvmFXJvfGLpLP"
content-type
Content type of the request body. Must be "application/json". This header is required for every request
authorization
The authorization key header is used to verify the request sender. This header is required for every request

Example: "AMZN-PAY-RSASSA-PSS PublicKeyId=AHEGSJCM3L2S637RBGABLAFW, SignedHeaders=accept;content-type;x-amz-pay-date;x-amz-pay-host;x-amz-pay-region, Signature=lDCyYfDN7ni7zfWQz/KvC89qSrZZidsYmZqqORBye/7zHCAR26svJh5DDZnEHkTvcJI/H/NyxzmPyAJpLEGaD7G3NKboIXLxuZYLUY2uS1NLkUMGAkP18NSie0AwuRuD2dngHw6ZIYJWtYBUCbDfAcsH6aCZjjRP+MjKqaIc6Pdwqcch/jXkDKhC0NhlCRQr1v50sI1cFK6rWhzc3qIQ/OGPdb5Oi+NfKWzg7oCxZrbvS6qpSi8u+Wr1qxIf51atWWtkbZH/ZWB6e6Q8V+ssOez/+0apXkOIc+Y2wPMP4SV7xqHDnvqTWOfZpRp/mFo7m/P9ayc730jrwQ65lalj5w=="
x-amz-simulation-code
The simulation code header is used to trigger specific responses. See Use Sandbox simulations for more information. This is an optional header

Example: "AmazonCanceled"

Request verification

Amazon Pay verifies the request sender using the authorization header. See Amazon Pay signature for more information on how generate the request header.


SDK

Use an Amazon Pay SDK to simplify the integration. Please reach out to your Amazon Pay account manager if you don’t see a SDK in your preferred language.

PHP: https://github.com/amzn/amazon-pay-sdk-v2-php

.NET: https://github.com/amzn/amazon-pay-sdk-v2-dotnet

Java: https://github.com/amzn/amazon-pay-sdk-v2-java