API introduction
Objects
There are 4 primary objects that you can use to complete your payments with Amazon Pay: CheckoutSession, ChargePermission, Charge, and Refund. Each represents a distinct payment operation or agreement, and each has different periods of relevance and use. Please be aware that these objects contain buyer information and you should only collect as much information as needed to complete the checkout and fulfill your orders. Any buyer information that is collected should be stored securely.
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.
Charge Permission
A Charge Permission object represents buyer consent to be charged. You can either request a one-time or a recurring Charge Permission object.
You can use a one-time Charge Permission to capture up to the total order amount while the Charge Permission is in a Chargeable state. You should review the reason code to determine why you can’t charge the buyer if the Charge Permission is in a Non-Chargeable state. The one-time Charge Permission will move to a Closed state after the total order amount has been captured, if it’s canceled, or it expires after 180 days.
You can use a recurring Charge Permission to charge the buyer on a recurring basis while the Charge Permission is in a Chargeable state. You should review the reason code to determine why you can’t charge the buyer if the Charge Permission is in a Non-Chargeable state. The recurring Charge Permission will move to a Closed state after if it’s canceled or after the expiration date.
You can use either Charge Permission types to retrieve relevant checkout details needed to complete the order(s) such as buyer name, buyer email, and shipping address. Note that you can only retrieve checkout details for 30 days after the time that the one-time Charge Permission was created.
Charge
A Charge represents a single payment transaction. Use a Charge to either authorize an amount and capture it later, or authorize and capture payment immediately.
Depending on the integration pattern, you can either create a Charge using a valid Charge Permission, or create it as a result of a successful Checkout Session. A successful Charge will move from Authorized to CaptureInitiated to Completed state. The Authorized state may be preceded by a Pending state if you set canHandlePendingAuthorization to true, or payment was captured more than 7 days after authorization. See asynchronous processing for more information. An unsuccessful Charge will move to a Declined state if payment was declined, and move to a Canceled state if the Charge is explicitly canceled, or the Charge expires after 30 days in the Authorized state.
Refund
A Refund allows you (the merchant) to refund some or all of a previously-captured Charge to the buyer. A refund can only be initiated on a previously captured Charge, and multiple Refunds can be initiated on a single Charge.
Amazon Pay processes refunds asynchronously. Refunds start in a Pending state before moving to a Completed or Declined state, depending on whether or not the operation was successful. You must set up instant payment notifications (IPNs), or implement a polling mechanism to query Get Refund API for updates. See asynchronous processing for more information.
API basics
Endpoint
| URL parameter
|
Description
|
| environment
|
Amazon Pay environment Possible values: "sandbox" or "live" |
| version
|
Amazon Pay API version Possible values: "v1" or "v2" |
Headers
At a minimum, you must set the x-amz-pay-date, content-type, x-amz-pay-region and authorization headers on every request you make to Amazon Pay. Additionally, you must set the x-amz-pay-idempotency-key header for all requests that create a new resource.
| 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 the following 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-V2 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" |
| x-amz-pay-region
|
The region the request is made from. Requests sent to the wrong region will be declined Accepted values: "na", "eu", "jp" |
Request verification
Amazon Pay verifies the request sender using the authorization header. Amazon Pay recommends implementing a key rotation strategy for the keys used to build the signature to prevent unauthorized access. In Seller Central go to the Integration Central tab to create/upload a new set of keys, then delete your old keys. See signing requests for more information on how to generate the request header.
API throttling limits
Amazon Pay APIs have throttling limits to protect against burst traffic and ensure service availability. Requests that have been throttled will return a 429 HTTP status code, see error handling for information on how to handle throttled requests.
Communication protocol
Amazon Pay blocks requests made using TLS 1.0 to ensure secure communication. We recommend using TLS 1.2 but you can use TLS 1.1 if you do not need to implement instant payment notifications. IPNs will not work with TLS 1.1.
SDK
Use an Amazon Pay SDK to simplify the integration.
# Install using Composer
composer require amzn/amazon-pay-api-sdk-php
Source code: https://github.com/amzn/amazon-pay-api-sdk-php
# Install using Visual Studio Package Manager Console
PM> Install-Package Amazon.Pay.API.SDK -Version 2.7.1
# Install using .NET Core CLI
> dotnet add package Amazon.Pay.API.SDK --version 2.7.1
Source code: https://github.com/amzn/amazon-pay-api-sdk-dotnet
# Install using Maven
<dependency>
<groupId>software.amazon.pay</groupId>
<artifactId>amazon-pay-api-sdk-java</artifactId>
<version>2.6.0</version>
</dependency>
# Install using Gradle
implementation 'software.amazon.pay:amazon-pay-api-sdk-java:2.6.0'
Source code: https://github.com/amzn/amazon-pay-api-sdk-java
// Install module as a dependency
npm i @amazonpay/amazon-pay-api-sdk-nodejs
Source code: https://github.com/amzn/amazon-pay-api-sdk-nodejs