Designing breach settlement ACH clearing exception and settlement failure UI in Figma: CLR-EXC-*, SETTLE-FAIL-*, and post-ACK recovery

Quick answer

Clearing exception UI covers the dangerous middle: processor accepted the file (SUB-ACK-) but individual ACH items failed, reversed, or never settled—before TRACE- proves money landed. Design CLR-EXC- item-level exceptions* linked to pay_id and SUB-ACK-, SETTLE-FAIL- recovery workspaces that route to returned payment, payee correction, or void/recall, and timeline states that never tell claimants “paid” until bank confirmation or proof of payment rules pass. Operators need clearing codes (R01, R02, administrative return, late reject) mapped to fix owners; claimants need plain-language “delayed” or “action needed” without ACH jargon. Start from the Figma guides hub and pair with progress indicators, tables, and Dev Mode handoff.

---

Who this is for

• Product designers where status portals jump from “processing” to “paid” on SUB-ACK alone—then support explodes when items return days later.
• Treasury ops reconciling partial clearing files against fund reconciliation REC-* periods.
• Counsel and auditors proving SETTLE-FAIL-* handling did not double-pay on re-export.

---

Post-ACK clearing lifecycle

ClearingOutcome — CLR-EXC-992-008 · item: PAY-992-4412 · parent SUB-ACK-992-014
├── Preconditions (from [ACK/NACK UI](/designing-breach-settlement-payment-submission-acknowledgment-and-processor-nack-remediation-ui-in-figma/)):
│   ├── SUB-ACK-* full or partial accept · FILE-NACHA-* hash locked
│   ├── pay_id marked clearing_in_flight (not settled)
│   └── TRACE-PEND-* opened per accepted item
├── Clearing states (operator + portal-safe mapping):
│   ├── submitted → in_clearing → settled | failed | returned | voided
│   ├── CLR-EXC-* when failed/return before settlement date
│   └── SETTLE-FAIL-* bundle when batch anomaly (cutoff miss · ODFI reject)
├── ID namespace:
│   ├── CLR-EXC-* (item exception) · SETTLE-FAIL-* (batch/settlement failure)
│   ├── CLR-CODE-* (normalized return reason) · RECOVERY-* (remediation plan)
│   ├── LOG-CLR-* (audit) · TIMELINE-EVT-* (claimant events)
│   └── LINK-RET-* bridge to RET-* when item becomes [returned payment](/designing-breach-settlement-returned-payment-and-reissue-ui-in-figma/)
├── Outcomes:
│   ├── Settled → close TRACE-PEND-* · await TRACE-* match
│   ├── CLR-EXC-* → block “paid” · open RECOVERY-*
│   ├── SETTLE-FAIL-* → freeze wave subset · counsel flag if dollar threshold
│   └── Duplicate recovery blocked by IDMP-* ([idempotency UI](/designing-breach-settlement-payment-idempotency-and-duplicate-submission-prevention-ui-in-figma/))
└── Claimant rule: “Processing” until settled+confirmed; “Delayed” on CLR-EXC-* with no bank details

Signal	Admin primary action	Claimant-safe copy
In clearing (normal)	Monitor SLA	“Payment processing”
CLR-EXC- (account)*	BENE-UPD-* or call center script	“We need updated payment details”
CLR-EXC- (admin return)*	Ops review · possible RET-*	“Payment delayed—working on it”
SETTLE-FAIL- (batch)*	Halt related SUB-* · QA halt	No wave-wide panic banner
Settled + TRACE-*	Proof of payment	“Paid” per policy

Verdict: SUB-ACK- means intake accepted—not that every PAY- cleared.** CLR-EXC-* is the UI home for item-level truth until TRACE-*.

---

SETTLE-FAIL-* recovery workspace

SettlementFailureQueue — SETTLE-FAIL-992-002 · wave: WAVE-992-04 · linked SUB-ACK-992-014
├── Summary:
│   ├── failure_class (cutoff · ODFI · liquidity · processor outage)
│   ├── affected_pay_count · dollar_in_clearing
│   ├── compare to [escrow ALLOC-*](/designing-breach-settlement-claims-fund-escrow-and-interest-allocation-ui-in-figma/)
│   └── Related [NACHA export](/designing-breach-settlement-payment-file-generation-and-nacha-preview-ui-in-figma/) version
├── Item table (CLR-EXC-* rows):
│   ├── pay_id · clm_id · amount · clearing_state · CLR-CODE-*
│   ├── suggested RECOVERY-* (reissue · void · wait · escalate)
│   ├── owner_enum (treasury · ops · claimant · counsel)
│   └── CTA: open BENE · RET-* · [payment inquiry](/designing-breach-settlement-payment-inquiry-and-where-is-my-payment-ui-in-figma/)
├── Bulk actions:
│   ├── Export for [call center](/designing-breach-call-center-and-agent-script-ui-in-figma/) scripts
│   ├── Link to [fund reconciliation](/designing-breach-settlement-fund-reconciliation-and-bank-matching-ui-in-figma/) unmatched bucket
│   └── Request counsel review when SETTLE-FAIL-* triggers APR-PAY-* hold
└── Wave card:
    ├── Items settled vs CLR-EXC-* vs pending
    ├── Block next SUB-* if SETTLE-FAIL-* severity=critical
    └── CTA: Apply RECOVERY-* batch with idempotency preview

Use search filters on CLR-CODE-* and badges for clearing_state. Empty states when all items leave clearing_in_flight.

---

Comparison: CLR-EXC-* vs FILE-NACK-* vs RET-*

Stage	When it fires	UI home	Typical fix
FILE-NACK-*	File rejected at intake	ACK/NACK remediation	Regenerate FILE-NACHA-*
CLR-EXC-*	Item fails during clearing	This article	BENE · wait · void
RET-*	Post-settlement return	Returned payment	Reissue · UCF

Best for: Teaching ops which console to open—NACK is not “returned check.”

---

Integration with validation, gates, and QA

1. PAY-VAL-* should not claim to prevent all CLR-EXC-—but feed RULE-PKG- updates when CLR-CODE-* clusters repeat.
2. GATE-PAY-* must stay released through clearing; new holds on CLR-EXC-* need explicit RECOVERY-* type.
3. HALT-QA-* can sample cleared items before portal “paid” copy auto-sends.
4. Timeline notifications should emit TIMELINE-EVT-* on CLR-EXC-* only when notify_policy allows—avoid duplicate emails on transient states.

Claimant portal: show stepper substeps (Submitted → Accepted by bank → Clearing → Confirmed paid)—never skip “Clearing.”

---

Handoff checklist (Dev Mode)

• ClearingException — clr_exc_id (CLR-EXC-*), pay_id, sub_ack_id, clr_code_enum, clearing_state_enum, recovery_id optional.
• SettlementFailure — settle_fail_id (SETTLE-FAIL-*), sub_ack_id, failure_class_enum, severity_enum, halt_sub_flag.
• ClearingRecoveryPlan — recovery_id (RECOVERY-*), clr_exc_id, action_enum (reissue, void, wait, escalate), idempotency_key.
• ClaimantTimelineEvent — timeline_evt_id (TIMELINE-EVT-*), clm_id, public_copy_key, admin_only_flag.
• ClearingAuditLog — log_clr_id (LOG-CLR-*), actor, payload_hash.

---

Common mistakes

Mistake	Why it hurts	Fix
Mark paid on SUB-ACK	Returns surprise claimants	Settled + TRACE-* gate
Expose R-codes to claimants	Confusion	public_copy_key map
No LINK-RET-*	Duplicate RET-* records	Bridge when item returns
Reissue without void check	Double pay	RECOVERY-* + IDMP-*
Wave-wide “failed” banner	Panic	Item-level CLR-EXC-*
Ignore partial SUB-ACK	Wrong pay_ids in queue	Split accepted vs rejected sets
No SLA on in_clearing	Stuck money invisible	Aging column + alerts
Skip reconciliation bucket	REC-* drift	SETTLE-FAIL-* → unmatched

---

Recommended workflow

1. Extend status portal stepper with clearing substates and admin-only CLR-CODE-* drawer.
2. Design SETTLE-FAIL- queue* beside bank confirm unmatched view.
3. Map CLR-CODE- to RECOVERY- templates** with deep links to BENE and RET modules.
4. Prototype idempotency preview on batch RECOVERY-* apply.
5. Align call center scripts with TIMELINE-EVT-* public_copy_key—not raw ACH text.

---

FAQ

CLR-EXC-* vs returned payment RET-*?

CLR-EXC- is pre-settlement or in-flight failure* · RET-* is post-settlement return—LINK-RET-* connects them when the same pay_id transitions.

Should pre-export validation block clearing issues?

It blocks predictable errors · CLR-EXC-* handles runtime bank/processor outcomes—feed patterns back into RULE-PKG-*.

Partial SUB-ACK and mixed clearing?

Split queues · accepted pay_ids enter clearing · rejected stay in NACK remediation.

Void/recall during in_clearing?

RECOVERY- type=void* · show cutoff timer · never duplicate with active SUB-* without IDMP-* check.

Claimant sees “paid” then CLR-EXC-*?

Policy violation · audit TIMELINE-EVT-* order · prefer “confirmed paid” only after TRACE-*.

---

Next steps

• Design breach settlement payment submission acknowledgment and processor NACK remediation UI in Figma — before clearing begins
• Design breach settlement bank confirmation and trace matching UI in Figma — after items settle
• Design breach settlement returned payment and reissue UI in Figma — when clearing becomes a return
• Design breach settlement payment idempotency and duplicate submission prevention UI in Figma — safe RECOVERY-* and reissue
• Design breach settlement claim status portal and claimant dashboard UI in Figma — timeline substeps