Sample Store - Credit Card Entry
Disclaimer: This document contains sample content for illustrative purposes only. Organizations should follow their own established best practices, security requirements, and compliance standards to ensure solutions are production-ready.
Overview
This page provides a consolidated view of all the capabilities, APIs, and documentation required to implement a Just Walk Out store using credit card entry where the retailer manages the full payment lifecycle. Amazon handles shopper identity at the gate and charge calculation, while the retailer orchestrates payment operations and retrieves data for receipts and reconciliation.
Store Profile
| Attribute |
Value |
| Entry Method |
Credit card |
| Identity Verification |
Amazon-managed |
| Charge Calculation |
Order Delegation via Create Purchases API |
| Payment Orchestration |
Retailer-managed via Payment Service APIs |
| Receipt Data |
Get Transactional Data + Get Shopper Identity APIs |
APIs in Scope
| API |
Endpoint |
Purpose |
| Shopper Authorization |
POST /v1/fraudandabuse/shopperauthorization |
Authorize or deny shopper at gate entry (Retailer Managed F&A) |
| Create Purchases |
POST /v1/order/purchases |
Receive cart and calculate pricing (Order Delegation) |
| Adjust Charge |
POST /v1/adjust/charge |
Adjust the pre-auth to the cart total |
| Cancel Charge |
POST /v1/cancel/charge |
Cancel the pre-auth (empty cart) |
| Capture Charge |
POST /v1/capture/charge |
Capture the adjusted amount |
| Refund |
POST /v1/refund |
Refund a captured charge |
| Report Payment Status |
POST /v1/feedback/payment-status |
Report debt payoff to restore store access |
| Get Transactional Data |
POST /v1/payment/transactional-data |
Retrieve EMV data for receipts |
| Get Shopper Identity |
POST /v1/identity/shopper |
Retrieve shopper email for receipt delivery |
1. Shopper Entry — Fraud & Abuse Authorization
When the store uses Retailer Managed F&A, Amazon calls the retailer's Shopper Authorization API at gate entry to determine whether the shopper should be allowed in. The retailer uses this callback to enforce bad debt policies — denying entry to shoppers with outstanding balances.
Key Documentation
How It Works
Amazon calls POST /v1/fraudandabuse/shopperauthorization each time a shopper taps their credit card at the gate. The retailer returns an authorization decision.
| Response |
Gate Action |
When to Use |
| APPROVED |
Gate opens |
Shopper has no outstanding balance |
| DENIED |
Gate remains closed |
Shopper has outstanding bad debt |
Bad Debt Enforcement at Entry
When a shopper has unresolved bad debt (e.g., a DECLINED Adjust Charge from a prior visit), the retailer tracks this internally. On the shopper's next visit, the F&A callback gives the retailer the opportunity to deny entry until the debt is resolved via the self-service portal.
| Step |
Action |
| 1 |
Shopper taps credit card at gate |
| 2 |
Amazon calls POST /v1/fraudandabuse/shopperauthorization |
| 3 |
Retailer checks internal bad debt records for the shopper |
| 4a |
No outstanding debt → return APPROVED → gate opens |
| 4b |
Outstanding debt exists → return DENIED → gate remains closed |
2. Charge Calculation — Ordering Connector
After the shopper exits, Amazon calls the retailer's Create Purchases API with the virtual shopping cart. The retailer calculates pricing, applies promotions and taxes, and returns a purchaseId. This is the Order Delegation model where the retailer owns charge calculation.
Key Documentation
How It Works
- Shopper exits the store
- Amazon sends the virtual cart to the retailer via
POST /v1/order/purchases
- Retailer calculates pricing, promotions, and taxes using their POS system
- Retailer returns a purchaseId for cross-system tracking
- Empty carts return an empty purchaseId and trigger pre-auth cancellation
3. Payment Lifecycle
After the shopper exits and Amazon calculates the cart, the retailer manages the payment flow.
Key Documentation
Payment Flow
| Step |
API |
Trigger |
| 1. Order Delegation |
POST /v1/order/purchases |
Amazon sends cart after shopper exits |
| 2. Adjust |
POST /v1/adjust/charge |
purchaseId returned, cart total known |
| 3a. Capture |
POST /v1/capture/charge |
Adjust returns APPROVED |
| 3b. Cancel |
POST /v1/cancel/charge |
Empty cart or adjust not needed |
| 3c. Bad Debt |
— |
Adjust returns DECLINED → retailer records bad debt (see below) |
| 4. Refund (optional) |
POST /v1/refund |
Shopper requests refund (within 30 days) |
| 5. Get Data |
POST /v1/payment/transactional-data |
After capture, for receipt generation |
| 6. Get Identity |
POST /v1/identity/shopper |
For receipt delivery via email |
Bad Debt Tracking on Adjust Decline
When POST /v1/adjust/charge returns DECLINED, the payment cannot be collected for that shopping trip. The retailer should:
- Record the outstanding balance against the shopper's payment instrument in their internal bad debt system
- Use this record to deny the shopper at gate entry via the F&A Shopper Authorization API (
POST /v1/fraudandabuse/shopperauthorization) on subsequent visits
- Direct the shopper to the self-service portal to pay off the outstanding balance and regain store access
4. Testing
Test Plan
| Test Plan |
Link |
| Credit Card Entry Test Plan |
Test Plan |
Existing Test Cases
Testing Phases
5. Shopper Self-Service Portal
Important: When the retailer manages the post-purchase experience (receipts, refunds, and payment orchestration), a shopper-facing self-service portal is required. This portal allows shoppers to pay off outstanding balances (bad debt) to regain store access.
Why a Portal Is Needed
When a shopper has bad debt (declined adjustment, partial capture, expired pre-auth), they are denied store entry on subsequent visits. The portal provides a payment channel to resolve the outstanding balance, after which the retailer calls the Report Payment Status API to clear the balance in Amazon's system and restore store access.
Portal Capabilities
| Capability |
Description |
APIs Used |
| Receipt Lookup |
Search past shopping trips by date, payment card, or transaction ID |
Get Transactional Data, Get Shopper Identity |
| Refund Request |
Submit a refund request with reason code; track refund status |
Refund (POST /v1/refund) |
| Outstanding Balance View |
Display current outstanding balance with breakdown by shopping trip |
Internal bad debt records |
| Debt Payoff |
Process payment to resolve outstanding balance |
Payment processor + Report Payment Status (POST /v1/feedback/payment-status) |
| Debt Resolution Confirmation |
Confirm balance cleared and store access restored |
Report Payment Status |
Outstanding Balance Payoff Flow
The payoff flow depends on the Fraud & Abuse (F&A) strategy configured for the store.
Amazon Managed F&A
When Amazon manages gate authorization decisions, the retailer must report the debt payoff to Amazon so the shopper can be re-authorized at the gate.
| Step |
Action |
| 1 |
Shopper authenticates on the portal (e.g., by payment card lookup or email) |
| 2 |
Portal displays outstanding balance with trip-level breakdown |
| 3 |
Shopper submits payment via the retailer's payment processor |
| 4 |
Retailer confirms payment and calls POST /v1/feedback/payment-status with the settledAmount |
| 5 |
Amazon clears the outstanding balance and re-authorizes the shopper at the gate |
Retailer Managed F&A
When the retailer manages gate authorization decisions, the retailer clears the outstanding debt directly in their own system. No call to Amazon is required since the retailer controls the gate decision.
| Step |
Action |
| 1 |
Shopper authenticates on the portal (e.g., by payment card lookup or email) |
| 2 |
Portal displays outstanding balance with trip-level breakdown |
| 3 |
Shopper submits payment via the retailer's payment processor |
| 4 |
Retailer clears the outstanding debt for the shopper in their internal system |
| 5 |
Shopper is re-authorized at the gate on their next visit (retailer's F&A check passes) |
6. Operational Readiness
End-to-End Flow
┌─────────────────────────────────────────────────────────────────┐
│ SHOPPER ENTRY │
│ │
│ 1. Shopper taps credit card at gate │
│ 2. Amazon verifies payment instrument │
│ 3. Amazon calls ──► POST /v1/fraudandabuse/shopperauthorization │
│ ├── APPROVED ──► pre-auth placed on card ──► gate opens │
│ └── DENIED (bad debt) ──► gate remains closed │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ SHOPPING │
│ │
│ Shopper picks up items ──► Amazon tracks virtual cart │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ SHOPPER EXIT & CHARGE │
│ │
│ 1. Shopper exits store │
│ 2. Amazon sends cart to retailer │
│ 3. Retailer calls ──► POST /v1/order/purchases │
│ └── Returns purchaseId (or empty for empty cart) │
│ 4. Retailer calls ──► POST /v1/adjust/charge │
│ ├── APPROVED ──► POST /v1/capture/charge │
│ └── DECLINED ──► Record bad debt ──► deny at next entry │
│ 5. Empty cart ──► POST /v1/cancel/charge │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ POST-PURCHASE │
│ │
│ 1. Retailer calls ──► POST /v1/payment/transactional-data │
│ 2. Retailer calls ──► POST /v1/identity/shopper │
│ 3. Generate receipt with EMV data + shopper email │
│ 4. Refund (if needed) ──► POST /v1/refund (within 30 days) │
│ │
│ Outstanding Balance Payoff (via Shopper Self-Service Portal): │
│ │
│ Amazon Managed F&A: │
│ 5a. Shopper logs into portal ──► views outstanding balance │
│ 6a. Shopper pays balance ──► retailer payment processor │
│ 7a. Retailer calls ──► POST /v1/feedback/payment-status │
│ └── Amazon clears debt ──► shopper re-authorized at gate │
│ │
│ Retailer Managed F&A: │
│ 5b. Shopper logs into portal ──► views outstanding balance │
│ 6b. Shopper pays balance ──► retailer payment processor │
│ 7b. Retailer clears outstanding debt in internal system │
│ └── Shopper re-authorized at gate (retailer F&A passes) │
└─────────────────────────────────────────────────────────────────┘
