Payment Processing
- Summary
- Supported payment processors
- Checkout Service vs. Payment Service Comparison
- Considerations
- Payment Processing overview
- Cart Total Adjustment and Payment Processing Workflow
- Get Transactional Data
- Pre-authorization
Summary
Our payment integrations let you optimize for the shopper experience, speed of deployment, ease of management, and level of integration that best match your business needs.
Amazon is pre-integrated with selected payment facilitators and offers two payment integration options:
-
Checkout Service: Amazon manages the payment orchestration while you continue to use your preferred payment processor. You submit the priced cart through the Checkout API and Amazon handles the rest.
-
Payment Service: You control the orchestration of payment calls, such as Adjust, Capture, Cancel, and Refund.
Supported payment processors
Just Walk Out technology supports several payment processors, including:
- Adyen
- Chase Paymentech (PTech)
- FreedomPay
- Shift4
- Stripe
- Worldpay
This list is not exhaustive, and processor availability varies based on the store location (country/region). Contact your Amazon representative to confirm which payment processors are available for your stores.
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 72 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
Cart Total Adjustment and Payment Processing Workflow
Pre-authorization hold is placed on shopper's
payment card when they enter the store. Client->>Cart: Cart total calculated Cart->>Adjust: Adjust Cart Total
(Adjust pre-auth to match actual purchase amount) Note over Adjust: Evaluate HTTP
Status Code alt Status Code NOT 200 alt 400 Error Path (NOT Retriable) Adjust-->>Client: 400 Bad Request Note over Client: Invalid request parameters.
Partner-side issue.
Will NOT resolve with retry.
Partner must fix and resubmit. Client->>Alert: Create Alert / Incident Ticket else 403 Error Path (NOT Retriable) Adjust-->>Client: 403 Forbidden Note over Client: Authentication/Authorization issue.
NOT retriable.
Partner must resolve auth credentials. Client->>Alert: Create Alert / Incident Ticket else 429 Error Path (Retriable with Backoff) Adjust-->>Client: 429 Too Many Requests Note over Client: Partner is calling too frequently.
Must back off before retrying. alt Response header contains wait time Client->>Client: Wait time specified in
response header else No wait time in header Client->>Client: Wait default time end Client->>Adjust: Re-try Adjust Cart Total
(with backoff) else 500 Error Path (Retriable with Backoff — 48hr Window) Adjust-->>Client: 500 Server Error Note over Client: System error. Retriable with
backoff algorithm (not back-to-back).
48-hour retry window. alt Within 48-hour retry window Client->>Client: Wait (backoff algorithm) Client->>Adjust: Re-try Adjust Cart Total else 48-hour window expired Client->>Alert: Create Alert / Incident Ticket
(Retry window exhausted) end end else Status Code 200 alt 200 Approved Path Adjust-->>Client: 200 Approved Client->>Capture: Capture Payment Capture-->>Client: Capture Response Client->>GTD: Get Transactional Data
(Retrieve EMV receipt data) GTD-->>Client: EMV Receipt Data Client->>Reporting: Report Payment Status Reporting->>Reporting: Did we capture full payment? alt Full Payment Captured = Yes Reporting-->>Client: Payment Complete ✓ else Full Payment Captured = No Reporting-->>Client: Report Payment Information
(Remediation required) end else 200 Declined Path Adjust-->>Client: 200 Declined
(includes authorizedAmount =
last successful adjustment) Note over Client: Declined options based on
organization's risk tolerance: alt Option 1: Write Off Full Amount Client->>Reporting: Write entire basket
amount to bad debt else Option 2: Partial Capture Client->>Capture: Capture returned authorizedAmount Capture-->>Client: Partial Capture Response Client->>Reporting: Write remaining balance
to bad debt else Option 3: Incremental Adjustments Client->>Adjust: Perform incremental adjustments
to find max approved amount Adjust-->>Client: Incremental adjustment response Client->>Capture: Capture max approved amount Capture-->>Client: Capture Response Client->>Reporting: Write remaining balance
to bad debt end end end
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.
