docs(cards): diagram the card transaction status transitions

[whoisglover]

Jira: ENG-11670 under ENG-11645

What this does

The reconciliation page explains how a card transaction moves between statuses. It draws those transitions as an ASCII block.

The block has fallen behind the model. It shows no path out of PARTIALLY_SETTLED into EXCEPTION, even though a pull can fail at any point after the authorization, and no path out of EXCEPTION at all. It also says nothing about reversals or expiries, which is the question integrators actually ask.

This PR replaces it with a state diagram and writes down the two rules the old block left out.

How it works

• The ASCII block becomes a mermaid stateDiagram-v2, matching the one on the transaction lifecycle page.
• The diagram shows both entry points, every clearing path, the three ways a transaction reaches EXCEPTION, and the way back out of it.
• New prose says the status is not stored. Grid re-derives it from the events recorded so far on every read, so it can move in either direction as later events arrive. That is why EXCEPTION is drawn with a way out.
• New prose says what a reversal does. A partial reversal releases part of the hold, lowers authorizedAmount, and leaves the transaction AUTHORIZED. A full reversal or an expiry releases the whole hold, so the transaction resolves as SETTLED with a settledAmount of zero.

Every claim is read off _gen_derive_current_status in ent_grid_card_transaction_schema.py, not inferred from the old docs. EXCEPTION to SETTLED is the credit path: a credit whose authorization was refused derives EXCEPTION, and once the return posts it derives SETTLED.

Tests

Docs only. No spec change, so no rebundle. make lint is unaffected.

History

This is the last piece of #935, which was merged into #934's branch by mistake instead of into main. The DECLINED status from that PR shipped separately in #957, and the decline reason is in #960.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Actions	Updated
grid-flow-builder	Ignored	Preview	Sep 12, 2026 3:55am UTC
grid-wallet-demo	Ignored	Preview	Sep 12, 2026 3:55am UTC

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
Grid	🟢 Ready	View Preview	Sep 12, 2026, 3:57 AM

[whoisglover]

@greptile review

[greptile-apps]

Confidence Score: 5/5

The documentation-only change appears safe to merge with no actionable new issues identified.

Summary

• Adds both authorization entry outcomes and the clearing paths through settlement.
• Documents transitions into and out of EXCEPTION.
• Explains that status is derived from recorded events on each read.
• Clarifies partial reversal, full reversal, and expiry outcomes.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    START([Start]) -->|Authorization approved| AUTHORIZED
    START -->|Authorization declined| DECLINED
    AUTHORIZED -->|A clearing posts| PARTIALLY_SETTLED
    PARTIALLY_SETTLED -->|Final clearing posts| SETTLED
    AUTHORIZED -->|Nothing remains outstanding| SETTLED
    AUTHORIZED -->|Funding pull fails| EXCEPTION
    PARTIALLY_SETTLED -->|Funding pull fails| EXCEPTION
    SETTLED -->|Funding pull fails| EXCEPTION
    EXCEPTION -->|Outstanding amount posts| SETTLED

Loading

_{Reviews (2) · Last reviewed commit: "docs(cards): diagram the card transactio..."}

[whoisglover]

@greptile review