Payment Processing
- Checkout Service vs. Payment Service Comparison
- Considerations
- Payment Processing overview
- Get Transactional Data
- Pre-authorization
Our payments integrations allow retailers to optimize for desired shopper experience, speed of deployment, ease of management, and level of integration to match business needs.
Amazon has pre-integrated with selected payment facilitators and offers two options for payment integrations.
The first is a payment service which allows retailers the ability to determine the orchestration of payment calls, ie. Adjust, Capture, Cancel.
The second service delegates the payment orchestration to Amazon while still allowing you to use your preferred payment processor through the use of a Checkout API.
With both options Amazon is not in the funds flow. The relationship is directly between the payment processor and the customer.
Checkout Service vs. Payment Service Comparison
The following table compares the two payment integration options to help you determine which approach best fits your business needs.
| Aspect | Checkout Service | Payment Service (Adjust / Capture) |
|---|---|---|
| Implementation | ||
| Payment orchestration | Amazon manages the full payment orchestration. You submit the priced cart via the Checkout API (/v1/checkout/carts) and Amazon handles the rest. |
You orchestrate the payment lifecycle by calling Adjust, Capture, Cancel, and Refund APIs in the correct sequence. |
| API integration effort | Single API call (POST /v1/checkout/carts) with line-item details and order totals. Amazon validates the cart and processes the charge. |
Multiple API calls required. You must implement the Adjust → Capture flow (and optionally Cancel and Refund), handle each response, and manage state transitions between calls. |
| Cart validation | Amazon validates that line items, promotions, taxes, and totals are consistent before processing the charge. Mismatches return specific error codes (e.g., CartContentValidationFailedException, CartOrderTotalInvalidException). |
No cart-level validation by Amazon. You are responsible for ensuring the adjustment amount is correct before calling Adjust. |
| Insufficient funds handling | Amazon handles the charge for the full cart amount. Partial capture is not supported. | You can handle declined adjustments with flexibility — capture the authorizedAmount returned in the Adjust response and write the remaining balance to bad debt, or perform incremental adjustments to find the maximum approved amount. |
| Error handling complexity | Fewer failure modes to handle. Errors are returned as specific exception types from a single API endpoint. | More failure modes across multiple APIs. You must handle errors at each step (Adjust, Capture, Cancel, Refund) and implement recovery logic for partially completed payment lifecycles. |
| Idempotency | Built-in via idempotentShoppingTripId. Multiple calls with the same ID are handled safely. |
You must ensure idempotency in your orchestration logic to prevent duplicate financial transactions on retries. |
| Receipt Management | ||
| Receipt generation | Amazon generates the shopper receipt automatically using the line-item data, promotions, taxes, and totals you submit in the Checkout API call. | You are responsible for building and managing your own receipt generation process. Amazon does not generate receipts in this model. |
| Receipt portal | Shoppers access receipts through the Amazon receipt portal — no development required on your side to provide a receipt lookup experience. | You must build and host your own receipt portal or integrate receipt delivery into your existing systems (e.g., email, app, or web portal). |
| Receipt data source | Amazon uses the checkout payload (line items, promotions, taxes, order totals) to populate the receipt. | You retrieve EMV data via the Get Transactional Data API for payment card details and combine it with your own cart and pricing data to build the receipt. |
| Receipt customization | Limited to the data fields supported by the Amazon receipt portal. Receipt format and branding are managed by Amazon. | Full control over receipt format, branding, layout, and content since you own the entire receipt experience. |
| When to Use | ||
| Best suited for | Retailers who want a faster integration with minimal payment logic, and are comfortable using the Amazon receipt portal for the shopper receipt experience. | Retailers who need full control over payment orchestration, want to handle partial captures for insufficient funds scenarios, and prefer to own the receipt experience with custom branding and delivery. |
Considerations
Based on the desired post purchase experience, customers chose between Amazon vending the receipt and receipt lookup experience vs the customer integrating with their current receipt processes.
Depending on the customer business strategy regarding shopper insufficient funds, the customer can capture partial payment by leveraging the payment service.
For efficient and flexible API interaction, it is recommended to utilize environment variables to store API endpoints and credentials. This approach allows for easy switching between development, testing, and production environments without code redeployment, significantly reducing overhead and simplifying the testing process.
Developers are encouraged to follow best practices including proper error handling, implementing retry logic, and logging API interactions for effective monitoring and debugging.
Note: The payment token has a limited lifespan, which begins at the time of the initial pre-authorization. This expiration period can vary depending on the specific payment processor being used. It is crucial to call the payment service before the token expires, as failure to do so risks the ability to capture the sale. While the exact timeframe may differ based on your payment processor, the token typically expires 46 hours after the shopping trip's initial start time. Once this period has elapsed, it is no longer possible to charge the cart. Attempting to process a cart after the token has expired will result in a ShoppingTripExpiredException being thrown.
Payment Processing overview
The payment flow begins when a customer's cart has been calculated and is ready for final charge processing. This document walks through the API sequence for completing the transaction.
Pre-Authorization Adjustment
When a shopper enters the store, a pre-authorization hold is placed on their payment card. Once the final cart total is calculated, this pre-authorization amount must be adjusted to match the actual purchase amount using the Adjust API.
Verification Process
The Adjust API response verifies whether the shopper's payment method can accommodate the total cart charge.
Successful Adjustments (200 Status Code)
Upon successful adjustment, you'll receive a 200 status code with one of two outcomes:
-
Approved Status
- Proceed to capture the payment using the Capture API
- After successful capture, retrieve EMV receipt data using the GetTransactionalData API
-
Declined Status
- If you receive a Decline, the response will include
the
authorizedAmountrepresenting the last successful adjustment. You have several options based on your organization's risk tolerance:- Write the entire basket amount to bad debt
- Capture the returned
authorizedAmountand write the remaining balance to bad debt - Perform incremental adjustments to find the maximum approved amount, then write the remaining balance to bad debt
- If you receive a Decline, the response will include
the
Error Handling
- 400 Error: Invalid request parameters
- 429 Error: Rate limiting (observe wait time in response header)
- 500 Error: System error requiring incident response
Get Transactional Data
You will use the get transactional data API method to collect EMV* data for the purpose of providing a customer receipt for the shopping trip as well as backoffice reconciliation.
*EMV, which stands for Europay, MasterCard, and Visa, is a global standard for secure payment transactions using a microprocessor chip embedded in credit and debit cards. This chip generates a unique code for each transaction, making it much more difficult to counterfeit cards compared to older magnetic stripe technology
Pre-authorization
When you enter a store, a temporary hold (pre-authorization) may be placed on your payment method to verify funds are available. This is not a charge. If you leave without buying anything, this hold is released. You can read more about pre-authorization setup for Just Walk Out see here.
When Amazon owns the payment orchestration, Amazon automatically cancels the pre-authorization as soon as your shopping trip is finalized and an empty cart is identified. Once canceled, your financial institution can immediately begin the process of releasing the reserved funds on your card.
In stores where the customer is responsible for payment orchestration, the customer is responsible for sending the cancel request to remove the pre-authorization. If the customer does not cancel within 72 hours, Amazon will initiate cancellation as a fallback.
Note: The timing of when funds become fully available depends on your bank or card issuer's policies, not Amazon.
The following table summarizes when you can expect an empty cart and who is responsible for canceling the pre-authorization hold on your payment method.
| Store Capabilities | Empty Cart Sent | Cancelling Pre-Authorization | Owner |
|---|---|---|---|
| Entry mechanism(s): Credit card Charge calculation: Amazon Payment orchestration: Amazon Payment processor: Amazon |
No | Amazon cancels the pre-authorization immediately after the shopping trip is finalized and an empty cart has been identified, allowing financial institutions the ability to immediately initiate their processes to release the reserved funds on a shopper's card when no payment was made. | Amazon |
| Entry mechanism(s): Credit card Charge calculation: Customer Payment orchestration: Customer Payment processor: Amazon |
No | Amazon cancels the pre-authorization immediately after the shopping trip is finalized and an empty cart has been identified, allowing financial institutions the ability to immediately initiate their processes to release the reserved funds on a shopper's card when no payment was made. | Amazon |
| Entry mechanism(s): Credit card Charge calculation: Customer Payment orchestration: Customer Payment processor: Customer selected |
No | Amazon cancels the pre-authorization immediately after the shopping trip is finalized and an empty cart has been identified, allowing financial institutions the ability to immediately initiate their processes to release the reserved funds on a shopper's card when no payment was made. | Amazon |
| Entry mechanism(s): Credit card Charge calculation: Customer Payment orchestration: Customer Payment processor: Customer selected |
No | Amazon cancels the pre-authorization immediately after the shopping trip is finalized and an empty cart has been identified, allowing financial institutions the ability to immediately initiate their processes to release the reserved funds on a shopper's card when no payment was made. | Customer |
| Entry mechanism(s): Credit card Charge calculation: Amazon Payment orchestration: Amazon Payment processor: Customer selected |
No | Amazon cancels the pre-authorization immediately after the shopping trip is finalized and an empty cart has been identified, allowing financial institutions the ability to immediately initiate their processes to release the reserved funds on a shopper's card when no payment was made. | Amazon |
| Entry mechanism(s): App/Badge Charge calculation: Customer Payment orchestration: Customer Payment processor: Customer selected |
Yes | The retailer can use their integration with the payment processor to cancel the pre-authorization directly, without requiring Amazon's involvement. | Customer |
| Entry mechanism(s): Multiple (e.g., App entry and Credit card entry) | When applicable based on the options above | If a store has a combination of configurations and one of the models supports empty cart detection, an empty cart result will be returned for all entry mechanisms within that store. | Based on the selection above |
Refer to the glossary below for term definitions:
- Entry mechanism: The method used by shoppers to enter the store, such as credit card tap or app/badge scan.
- Charge calculation: The party responsible for determining the final cart total and computing the charge amount — either Amazon or the customer (retailer).
- Payment orchestration: The party responsible for coordinating the sequence of payment API calls (adjust, capture, cancel) to complete the transaction.
- Payment processor: The payment facilitator that handles the actual financial transaction — either Amazon's pre-integrated processor or a customer-selected third-party processor.
- Empty cart: A shopping trip where the shopper enters the store but exits without purchasing any items, requiring the pre-authorization hold to be cancelled.
