Payment Processing
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.
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.
