Skip to content

Finding the boundary after settlement

A payment can settle successfully while the application fails to store its result. Returning a careful error is better than fabricating a successful URL, but it does not undo settlement. Resilience Gate records that cross-system boundary instead of describing the request as an atomic transaction.

Design decision examined. The paid route, settlement association, tests, and consistency documentation have linked history attributed to devSatym. This case examines the implemented limit; it does not claim the gap was eliminated or recovered in a new live test.

Verification and settlement through the facilitator happen before PostgreSQL persistence; successful creation needs both, while partial failure requires deliberate reconciliation
Settlement precedes durable URL persistence.

A client gets a payment challenge, asks the separate signer to sign, and submits the signed request. FastAPI sends server-owned terms, verifies and settles via the facilitator, then inserts the URL and replay receipt. A database failure after settlement is a consistency gap.

Source-derived explanation; not a live observation.
Read the diagram step by step
  1. An unpaid request receives a payment challenge.
  2. A paid request is verified and settled before durable creation.
  3. Database persistence can still fail after settlement.
  4. The implementation does not establish an atomic cross-system transaction or a refund workflow.
Public implementation sources

app/main.py · app/payment.py

The application route first looks for an existing destination. An ordinary repeat can return its short URL without another payment. For a new payment-enabled creation, missing authorization produces the 402 challenge with server-owned terms. The application then sends the submitted envelope and those terms to facilitator /verify, followed by /settle only after valid verification.

The payment validator requires boolean settlement success and a canonical transaction identifier before the result is persisted. HTTP 200 alone is insufficient. The application does not hold payer keys or submit chain transactions directly; the facilitator is the authority evaluating the signed envelope against the supplied requirements.

After validated settlement, the route attempts PostgreSQL insertion with the destination, code, settlement identifier, optional payer, and settlement time. Only a successful insert produces a new 201 response.

The invariant is new creation requires validated settlement and successful persistence. The ordering also creates a gap: the first side effect can complete before the second fails.

Replay association protects a database record

Section titled “Replay association protects a database record”

The database enforces unique destinations and a unique non-null settlement identifier. Conflict-safe insertion and subsequent lookups handle code collisions, destination reuse, and a settlement already associated with another URL. That settlement replay path returns 409 rather than creating a second mapping.

This database constraint does not prevent the preceding facilitator call. Settlement has already happened when the application checks the returned identifier. Permit2 nonce consumption and possible facilitator idempotency are separate layers outside this database association rule.

Concurrency also matters. Two requests for a previously absent destination can both pass the initial lookup and reach payment before one wins the unique destination insert. The ordinary reuse shortcut cannot be promoted into a universal no-extra-settlement guarantee.

A failed response is not proof that no payment occurred

Section titled “A failed response is not proof that no payment occurred”

If settlement succeeds and the required database operation then raises DatabaseUnavailable, the route returns 503. No URL success is invented, but the payer may already have a settled transaction. There is no distributed transaction, compensating refund, built-in reconciliation endpoint, or durable pre-settlement journal in this application.

Observation Point in the path What remains uncertain
Payment outcome settled increments Payment processing returned success URL persistence has not yet completed
URL-created counter increments / 201 A new database mapping was inserted This is not audited chain finality or a general settlement guarantee
Database 503 after settlement Required persistence failed A completed external side effect may require reconciliation
Replay 409 Settlement identifier is already associated It does not undo or suppress every prior facilitator call

The design contract requires deliberate reconciliation by the validated settlement identifier. That is an operational principle, not an implemented recovery workflow demonstrated by this repository. Blindly obtaining a fresh authorization and paying again can worsen the incident.

The implemented HTTP mapping also differs from the contract’s general malformed-response description. Transport/HTTP failures, malformed JSON, and non-object replies become facilitator-unavailable 503. Structurally invalid verification or settlement objects become invalid_response and currently map to 402. This explanation preserves that discrepancy rather than silently changing application behavior.

Commit 8e8934b7 introduces paid URL creation. Commit 2b052fc1 adds settlement audit fields, the unique association, and replay handling. Commit b18aa097 adds a hermetic application/facilitator contract test and documents the cross-system consistency limit.

The current payment header tests, replay test, and integration test demonstrate supplied-data behavior and server-owned facilitator terms. They do not establish a real chain transaction or recovery after settlement and database failure.

Separate the recorded smoke from the unproven failure case

Section titled “Separate the recorded smoke from the unproven failure case”

The verification report retains the sanitized owned-testnet sequence 402 → signed 201 → redirect 302 → replay 409. It supports the recorded HTTP/application replay path and its candidate identity. It is not a public live post-settlement database-failure recovery record, custody audit, mainnet test, or global exactly-once proof.

The next design question is how to make reconciliation durable and safe under partial failure and concurrent requests. This website analyzes that remaining risk without implementing a payment change. The paid-request workflow traces the full HTTP and metrics sequence; dependency boundaries places it alongside the other failure paths.

Open original image

Maintained by Satyam Agnihotri · DevOps & Cloud Engineer