Build checkout that recovers from uncertain payments

Application background

Ana buys a book from an online shop. When she presses Pay, the shop records her order, holds a copy of the book and asks a separate payment company to charge her card. Normally the payment company replies with a charge ID, and the shop shows a confirmation.

Now suppose the card is charged but the reply never reaches the shop. After waiting a fixed amount of time, the shop stops waiting. That is a timeout. It tells the shop that an answer is missing, not whether the charge happened.

Follow the missing payment reply

The status endpoint you will implement should expose that uncertainty. This is a proposed API excerpt, not an HTTP endpoint supplied by the local model:

GET /checkouts/order-7

{"id":"order-7","state":"payment_unknown"}

The repair operation looks up the original payment identity before changing this result to paid or deciding another action is needed.

Reconciliation means comparing the shop's record with the payment company's record and resolving the disagreement. Your project must make that repair possible without a second charge.

Your assignment

Deliver: Build checkout records and payment handling, including a repair command that finds an uncertain payment's actual outcome without charging the customer twice.

Required behavior: POST /checkouts requires an ID reused for retries of the same purchase and a cart fingerprint, a value identifying the exact items, quantities and prices agreed to. Reusing the request ID with a different cart must be rejected. GET /checkouts/{id} exposes pending, payment_unknown, paid, confirmed or refund_required. Timeout must never be translated into definitely_not_charged.

The required first milestone is a working local implementation of the behavior above. The numbered implementation steps define the scope. The cloud architecture is a later extension, not something the starter has already provisioned.

Get the code and run the supplied example

The code is in the public junior-to-staff repository. Install Git and Python 3.12+. No AWS account or Python packages are required for this first run. If you already have a checkout, use it and skip cloning.

git clone https://github.com/Soulful-Iris/junior-to-staff.git
cd junior-to-staff
python3 examples/architecture-starts/checkout_payment.py

Supplied file: examples/architecture-starts/checkout_payment.py. You can also read or download the source here (download file, source below).

"""Local mechanism demonstration for checkout-payment. No AWS resources are created."""
# A tiny provider fixture models a charge whose response was lost.
provider={}; order={'id':'order-7','state':'pending'}
key='payment:order-7:v1'
def charge(k):
    if k not in provider: provider[k]={'charge_id':'charge-91','amount_minor':1999}
    return provider[k]
charge(key)  # provider committed; simulate losing the response
order['state']='payment_unknown'
print('After timeout:',order)
evidence=charge(key)  # the SAME provider key resolves the same charge
order.update(state='paid',charge_id=evidence['charge_id'])
print('After reconciliation:',order,'provider charge count:',len(provider))

This program is a mechanism demonstration: it runs the small scenario in one process and prints the result. It is not an HTTP service, a complete application, or an AWS deployment. A successful run demonstrates this mechanism only. It does not establish the workload or failure guarantees of the application you will build.

Example output from the supplied run:

Generated IDs and timestamps may differ. Compare the state transitions and outcomes.

After timeout: {'id': 'order-7', 'state': 'payment_unknown'}
After reconciliation: {'id': 'order-7', 'state': 'paid', 'charge_id': 'charge-91'} provider charge count: 1

Set up your implementation workspace

Create work/checkout-payment/ in your checkout (or use a separate repository). Copy the supplied mechanism into that directory as mechanism.py, then extract its state transitions into functions you can call from your implementation. The record and module names below describe what you must implement. They are not a promise that files with those names already exist. Keep a README.md beside your implementation with its exact run commands and observed results.

Local components and state to implement

This table names the records, interfaces or decision inputs for your deliverable. Unless a name is explicitly linked to supplied source above, it is something you create. Implement the local state transitions first, then connect the HTTP, storage or worker boundaries required by the steps.

Implement the assignment

1. Persist checkout before contacting payment

Validate the cart and calculate money in integer minor units with currency. Store request ID, cart fingerprint and the reserved-stock reference. Exact replay returns the same checkout. Changed cart under that ID returns 409.

2. Record the payment attempt

Allocate one provider key for this order attempt and persist it before sending. Apply a bounded deadline. A timeout records payment_unknown. It does not clear the attempt key. Use a provider that supports deduplication and lookup for the required retry horizon.

3. Reconcile ambiguous outcomes

Implement reconcile.py to look up the attempt or safely repeat the same key under the provider’s contract. Validate webhook signatures and deduplicate provider event IDs. Handle callbacks arriving before, during or after polling with conditional state transitions.

4. Finalize or compensate

Commit paid evidence and order transition. If the inventory hold is gone, record refund_required or attempt an explicit new reservation according to product policy. Put confirmation/refund work in an outbox. A database rollback cannot undo a completed external charge.

Demonstrate the completed local result

Handoff: In your implementation README, include the start command, one successful operation, the failure case above and the resulting stored state or decision. State which dependencies are simulated. Someone with a fresh checkout should be able to reproduce this without your chat history.

Workload assumptions and capacity decisions

These are constructed exercise assumptions. The stated workload is a design target. The local demonstration does not establish that throughput. Use the estimation constants to check units before choosing capacity.

Map the local implementation to AWS

Deployment status: local only. Running the supplied command creates no AWS resources and configures no cloud connections. The diagram is a proposed deployment of the completed application. Each box needs either a deployed runtime, a provisioned service or an explicitly external dependency.

Read the diagram by following the arrows from the entry point: application code accepts the request or event, the state owner commits it, and any worker produces the later result. The table ties those roles to code and adapter work. Multiple boxes do not imply multiple Python files already exist.

Aurora owns order truth. The provider owns charge truth. A queue coordinates retryable work across those authorities. Their independent commits are the reason for a durable unknown state and compensating actions.

Provision resources, then connect the application

Use one disposable AWS environment for the cloud exercise. Put the named resources in infra/template.yaml or your existing IaC tool, pass resource IDs through configuration, and scope each runtime role to its own tables, buckets and queues. The diagram is a design to implement. It is not a claim that these resources have been deployed. Record the commands you used to deploy and remove the exercise resources.

For concrete provisioning commands, configuration wiring and cleanup, use the AWS foundation guide. It includes a deployable table/queue/object-storage foundation and explains which application and service adapters you still implement.

A provisioned queue or table does not make the local program use it. Configure resource IDs in the deployed runtime, replace the local adapter, and replay the same successful and failing operation against that runtime. Record the deployed commit and observable result, then remove the disposable resources using your infrastructure tool.

Extend the design after the baseline works

Worked follow-up: Add a second payment provider without charging twice

A charges order 41 but its response disappears. Sending the same order to B is not a retry from B's perspective. B has never seen A's idempotency key and may create a second charge.

Revised architecture. Follow the changed responsibility and failure path below. This is a design to implement. The supplied local example does not provision these components.

What to implement. Persist provider_id, attempt_id, cart fingerprint and provider key before submission. A router chooses the provider only when creating a new attempt. A timeout moves that attempt to UNKNOWN. A reconciliation worker queries the original provider and records its receipt or an unresolved outcome. After its safe retry window expires, stop automatic resubmission. Switching providers for that order requires a verified terminal outcome and an explicit new decision. Use the existing order store and SQS worker, with separate provider adapters and credentials.

Walk through the result. Make A report success through status lookup after the API timed out. The order becomes PAID using A's receipt. B receives zero calls for that attempt. Then create order 42 while A is disabled and show B handling that new attempt. Hand over both provider call ledgers.

Add two payment providers. Define which provider owns an attempt before failover: switching providers after a timeout can create two charges because their idempotency domains are independent. Route only new attempts automatically. Reconcile ambiguous existing ones with their original provider.