Checkout: Risk, testing, and operations

Defines a server-authoritative checkout workflow with priced snapshots, idempotent provider sessions, verified asynchronous fulfillment, inventory or entitlement safeguards, and reconciliation evidence.

Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.

Decision

Calculate price and eligibility on the server, persist an immutable checkout intent, and use the payment provider's hosted or tokenized flow. Fulfill from a verified asynchronous payment event, idempotently, then reconcile provider and internal ledgers.

Scope

Checkout intent, price snapshot, tax/discount inputs, provider session, return paths, webhooks, fulfillment, expiry, refunds handoff, risk controls, tests, and operations.
One-time or first-subscription checkout where provider events are authoritative for payment state.
Uncertain outcomes and reconciliation.

Outside this block

Storing raw card details or implementing a card vault.
A full accounting ledger or jurisdiction-specific tax determination.

Contract

The server resolves product, amount, currency, customer eligibility, discount, and tax profile; client totals are display-only.
A checkout intent has an immutable priced snapshot, owner, state, expiry, and idempotency identity.
Provider session creation reuses the intent identity and records provider references without exposing secret keys.
Return-page success is not fulfillment evidence; a verified provider event or server-side status check drives the state transition.
Event signature, account context, livemode/environment, event type, amount, currency, and intent mapping are verified.
Fulfillment and downstream email or entitlement issuance are idempotent and survive duplicate or out-of-order events.

Implementation guidance

Use states such as draft, session-created, processing, paid, fulfilled, expired, cancelled, and review-required with allowed transitions.
Keep payment state and fulfillment state separately visible.
Store raw provider event in protected retention when required, plus a normalized event and processing outcome.
Build reconciliation by provider object and money amount, not only by webhook count.

Failure handling and safeguards

If the return page arrives before the webhook, show processing and poll a safe internal status.
If amount/currency mapping disagrees, quarantine fulfillment and alert.
If fulfillment fails after payment, retry fulfillment under the same paid intent; do not charge again.

Verification and operations

Measure session creation, abandonment, payment success, processing age, duplicate events, signature failures, fulfillment lag/failure, mismatch, and reconciliation deltas.
Test provider sandbox and deterministic signed fixtures, including duplicate and reordered events.
Run daily reconciliation and alert on paid-but-unfulfilled intents.

The executable-looking examples in this package are fixtures and acceptance contracts. Run python tools/validate.py from the collection root to check package structure and metadata; then implement and execute the scenarios in the target repository.

Adoption assumptions

Names and numeric values in example.yaml are an adoption profile, not universal defaults.
The adopting team must map actors, data classes, error vocabulary, and ownership to its system.