Implement a persisted idempotent FastAPI POST

key=K, body=A first call  -> 201 payment P
key=K, body=A retry     -> 201 same payment P
key=K, body=B           -> 409 key reused

• Scope the key to the authenticated account.
• Hash a canonical representation of the meaningful request.
• Enforce one key per account with a database unique constraint.
• Store payment and replayable response atomically.
• Treat uniqueness races by re-reading the winner, not by creating again.

1. Normalize and hash the request before opening the command transaction.
2. Look up the account/key record and replay or reject when it exists.
3. Create the payment and completed idempotency record in one transaction.
4. On a uniqueness race, roll back and read the committed winner.
5. Return the stored status and public response body for every equivalent retry.

async def create_payment(command: CreatePayment, key: str, session_factory):
    request_hash = command.canonical_hash()
    async with session_factory() as session:
        async with session.begin():
            existing = await find_idempotency(session, command.account_id, key)
            if existing:
                return existing.replay_or_conflict(request_hash)

            payment = Payment.create(command)
            session.add(payment)
            await session.flush()
            response = PaymentOut.from_domain(payment).model_dump(mode="json")
            session.add(IdempotencyRecord.completed(
                account_id=command.account_id,
                key=key,
                request_hash=request_hash,
                status_code=201,
                response_json=response,
            ))
        return 201, response

# Unique(account_id, key) is required.
# Catch the constraint race outside this failed transaction,
# then open a fresh session and replay the committed winner.

The normal path uses an indexed key lookup plus bounded inserts. Storage grows with retained keys, so expiry and archival need a product policy.

• Two first requests can race before either sees a record.
• A response cannot be replayed before its business transaction commits.
• Canonical hashing must not change when JSON object key order changes.
• Expired keys need documented reuse semantics.

• Run concurrent identical requests and assert one payment exists.
• Reuse a key with a different amount and expect 409.
• Force the payment transaction to roll back and assert no completed key remains.
• Retry after a simulated lost response and verify the same public response.

• An in-memory dictionary fails across replicas and restarts.
• Checking then inserting without a unique constraint leaves a race.
• Storing only the key cannot detect a different request.
• Committing the key before the payment can permanently replay a result that never happened.