Ledger and Settlement View
Operational ledger entries for expected, received, swept, spent, refunded, and settled state
Ledger and Settlement View
Use this page for BDT-318 on the M6 Observability + Settlement Ops milestone.
The goal is to give operators and merchants a single traceable record of money movement from expected payment through settlement.
Ledger states
The ledger must represent the following states:
expectedreceivedsweptspentrefundedsettled
Each state transition should be idempotent. Replaying the same transition must not create duplicate rows or drift the balances.
Ledger entry contract
Each entry should be queryable by session or spend event and carry enough context for support review.
| Field | Meaning |
|---|---|
ledger_entry_id | Stable id for the record |
merchant_id | Merchant scope |
session_id | Payment session correlation |
spend_id | Outbound spend correlation when relevant |
wallet_id | Wallet that moved funds |
entry_type | One of the ledger states above |
status | Operational status such as pending, confirmed, failed, or cancelled |
chain / network | Chain context |
token | Token symbol |
amount | Amount moved |
fee_amount | Fee attributed to the entry |
tx_hash | On-chain transaction hash when available |
proof | Settlement or verification proof when available |
balance_before | Balance before the transition |
balance_after | Balance after the transition |
created_at | Entry creation time |
settled_at | Settlement time when the row reaches a final state |
Operator views
Support should be able to inspect the ledger in three ways:
- By session id, to understand a payment from initiation through confirmation.
- By spend event, to understand outbound movement and any fee impact.
- By merchant and date range, to reconcile a slice of activity.
Keep the view merchant-scoped. A merchant should never see another merchant's entries, even when the same chain or token is involved.
Export behavior
The ledger view can be exported for support review.
- Use a stable column order.
- Preserve the same field names in CSV and JSON exports.
- Filter exports by merchant and date range before pagination.
- Include the
tx_hashorproofvalue when it exists, but do not invent a placeholder. - Mask secrets and internal support notes.
Transition rules
expected -> receivedwhen Plaidly detects the payment.received -> sweptwhen funds are moved to the settlement path.swept -> settledwhen the final accounting state is confirmed.settled -> refundedonly if the business flow actually reverses value.- Expired sessions are not separate ledger entry types; record expiration in the session view unless value actually moved.