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.
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.
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.
If the buyer completes checkout within 24 hours, the Checkout Session will move to either a Completed state or Canceled state, depending on whether or not the checkout was successful. In the Completed state, you can use the Checkout Session to retrieve references to a Charge Permission. If payment authorization was requested, the response will also include references to a Charge. 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 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.
Successful completion of a Checkout Session returns a reference to a Charge Permission. In a Chargeable state, the Charge Permission can be used for one successful Charge capture. The Charge Permission will move to a Closed state after a successful Charge capture, if it’s canceled, or it expires after 180 days.
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
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, 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 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-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. See Amazon Pay signature for more information on how 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.
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