Agentic AI for Payment Exceptions: Sanctions Hits, Repairs, and the Release Decision an LLM Must Never Make (Real LangGraph Code)
Build a payment-exceptions agent in LangGraph: deadline-aware triage, sanctions-hit analysis, repair drafting and a human-gated release — with full code.
- Author
- Randhir Jassal
- Published
- Reading time
- 19 min read
- Views
- 4 views
Payments are the domain where "the happy path is already automated" is most literally true — straight-through processing has existed for decades, and a clean payment never touches a human. The cost lives entirely in the exceptions: the payment with a malformed beneficiary reference, the sanctions screening hit that's probably (but only probably) a false positive, the duplicate suspicion, the failed downstream leg — each needing context from three systems, a judgment call, and often a sign-off, under a hard clock, because payment cut-offs are real deadlines and a missed one is a client incident. The error costs are brutally asymmetric: block a legitimate payment and you have an angry client and a breached SLA; release a bad one and you have a loss, a regulatory incident, and possibly a sanctions violation measured in millions. This post builds the agent for that queue in LangGraph — deadline-aware triage, evidence gathering, sanctions-hit narratives, repair drafting — with the cardinal rule from the series flagship at its hardest setting: release / hold / reject is proposed by the model and decided by a human, every single time.
TL;DR
| What | How |
|---|---|
| Happy path | Untouched — STP stays deterministic, the agent never sees clean payments |
| Triage | Haiku classifies exception type + urgency from the cut-off clock |
| Evidence | Read-only tools: beneficiary history, sanctions-hit detail, duplicate scan |
| Sanctions hits | Agent drafts the false-positive narrative; it can NEVER clear a hit |
| Repairs | LLM proposes field fixes; scheme rules (IBAN, BIC, purpose codes) re-validate deterministically |
| Release | requires_human=True unconditionally — releasing money is never autonomous |
| Audit | Signed, hash-chained entry per exception: evidence + rationale + approver + clock |
- The agent's input is the exception queue, never the payment flow — STP rates are untouched by construction.
- Triage is deadline-aware: the same exception 4 hours vs 20 minutes before cut-off gets a different priority, not a different answer.
- ~60-80% of exceptions get a drafted disposition (release/hold/reject + rationale) a human can approve in one click (representative, per workflow class).
- Handling time per exception drops from 15-25 min to 3-5 min — review, not investigation.
- A sanctions hit is special-cased: the agent assembles the discrimination evidence but the clear/escalate decision follows your existing four-eyes process, unchanged.
- Repair proposals are re-validated by deterministic scheme rules — a hallucinated IBAN fails its checksum before any human sees it.
- Duplicate suspicion is resolved with deterministic matching first, LLM narrative second.
- The release service is idempotent and callable only with an approval token — not by any LLM path.
- Every disposition is one signed audit entry including the deadline state at decision time.
- Golden-set evals in CI: disposition accuracy, groundedness, and a hard zero-tolerance gate on "release" proposed for any true sanctions match.
The one mental shift: the agent's product is a disposition memo, not a payment instruction. It writes "release, because: beneficiary matched 47 prior payments, reference repaired per scheme rules, sanctions hit discriminated on DOB mismatch — evidence attached" — and a named human turns that memo into money movement. The memo can be wrong and cost you nothing; an autonomous release that's wrong once pays for every shortcut you didn't take.
The running example
Same platform as the series flagship and the reconciliation deep-dive: Python, LangGraph (typed state, checkpointing, interrupt()), Langfuse (self-hosted tracing + evals), Claude Opus for reasoning, Haiku for triage. Payments is the second domain deployed, after reconciliation proved the propose-approve-audit loop — because payments adds two things recon didn't have: a hard clock and a sanctions process you must not disturb. Code is illustrative reference (pin versions, confirm SDK signatures); metrics are representative of the workflow class, not a single audited deployment.
1. Scope — the agent lives in the exception queue only
The first decision mirrors reconciliation's "matching is not an AI problem": straight-through processing is not an AI problem either. Validation, enrichment, routing, and settlement of clean payments are deterministic, fast, and already work. The agent subscribes to the exception queue and nothing else.
payments in -> deterministic STP pipeline -> settled (95-99%, untouched)
|
+--> EXCEPTIONS (the residual) -> the agent
- missing/malformed reference or beneficiary data
- sanctions screening hit
- duplicate suspicion
- failed downstream leg
- funding / FX / cut-off issues
This matters commercially as much as technically: nobody has to re-certify the payment pipeline, because the payment pipeline didn't change. The agent is a new consumer of an existing queue, and its write path is one deterministic, gated service (section 6).
Representative metric: exception rates in this workflow class run 1-5% of volume; at tens of thousands of payments a day that's hundreds of human investigations — the entire ROI lives there.
2. Deadline-aware triage — urgency is data, not vibes
Payment exceptions have a property reconciliation breaks don't: a cut-off. The same malformed reference is routine at 9am and an incident at 15:40 when the clearing window closes at 16:00. Triage therefore scores two independent things: what kind of exception is this (Haiku) and how much clock is left (arithmetic — never the model).
TAXONOMY = ["repairable_data", "sanctions_hit", "duplicate_suspicion",
"failed_downstream", "funding_fx", "unknown"]
class TriageResult(BaseModel):
label: Literal[*TAXONOMY]
rationale: str
async def triage_exception(exc: PaymentException) -> QueueItem:
label = await haiku.ainvoke(triage_prompt(exc), response_format=TriageResult)
# Urgency is deterministic: minutes to the relevant cut-off, from refdata.
cutoff = scheme_cutoffs.for_payment(exc.payment) # scheme + currency + date
minutes_left = (cutoff - utcnow()).total_seconds() / 60
return QueueItem(
exception=exc,
label=label.label,
priority=priority_matrix(label.label, minutes_left), # code, not model
escalate_now=(minutes_left < 30 and exc.payment.amount > HIGH_VALUE),
)
Two rules that keep this honest:
- The model never computes urgency. Cut-offs come from reference data and the clock; an LLM guessing "this seems urgent" is noise wearing a suit.
- High-value + low-clock short-circuits to a human immediately with whatever evidence exists so far. An agent that spends eleven minutes beautifully investigating a payment that misses its window has optimized the wrong thing.
Representative metric: deadline-aware ordering alone — before any drafting — cuts missed-cut-off incidents in this workflow class by half or more, because the queue stops being first-in-first-out.
3. Evidence gathering — the four tabs, as tools
Like the reconciliation agent, the payments investigator gets read-only, typed tools, each returning sourced Evidence with an ID the explanation must later cite:
@tool
async def beneficiary_history(beneficiary_id: str) -> Evidence:
# Prior payments to this beneficiary: count, amounts, last seen, past repairs.
hist = await payments_store.beneficiary_history(beneficiary_id, months=24)
return Evidence(id=new_id(), source="payments_history", payload=hist)
@tool
async def sanctions_hit_detail(hit_id: str) -> Evidence:
# The screening engine's own output: matched list entry, fields, fuzzy score.
hit = await screening.hit_detail(hit_id)
return Evidence(id=new_id(), source="screening_engine", payload=hit)
@tool
async def duplicate_scan(pmt: Payment) -> Evidence:
# Deterministic: same amount+beneficiary+reference within a window.
dupes = await payments_store.find_candidates(pmt, window_hours=48)
return Evidence(id=new_id(), source="duplicate_scan", payload=dupes)
@tool
async def scheme_rules(scheme: str, ccy: str) -> Evidence:
# Format rules: IBAN structure, BIC validity, required fields, purpose codes.
rules = await refdata.scheme_rules(scheme, ccy)
return Evidence(id=new_id(), source="refdata", payload=rules)
beneficiary_history is the workhorse here, the way similar_resolved_breaks was for reconciliation: "47 prior payments to this exact beneficiary over two years, three with the same malformed reference, all repaired the same way" turns a judgment call into a review.
4. The two hard cases
4.1 Sanctions hits — draft the discrimination, never the decision
Sanctions screening engines are deliberately over-sensitive: fuzzy name matching produces hits where "Mohammed Al-Rashid, DOB 1961, Damascus" on a list collides with "Mohamed Rashid, DOB 1988, Mumbai" on a payment. Analysts resolve most hits as false positives by discriminating on the non-matching fields — and writing that discrimination up is slow, repetitive, and perfect agent work. The decision is not.
class HitAssessment(BaseModel):
discriminators: list[Discriminator] # field, list_value, payment_value, match/mismatch
cited_evidence: list[str] # required — guardian rejects uncited claims
narrative: str # the write-up an analyst would have produced
assessment: Literal["likely_false_positive", "possible_match", "insufficient_data"]
# NOTE: there is no "clear" and no "release" in this enum. On purpose.
async def assess_hit(state: AgentState, hit: Evidence) -> Proposal:
assessment = await opus.ainvoke(
hit_prompt(state.exception, hit, state.evidence),
response_format=HitAssessment,
)
return Proposal(
action="route_to_sanctions_review", # ALWAYS — regardless of assessment
payload={"assessment": assessment.model_dump()},
rationale=assessment.narrative,
confidence=confidence_from(assessment),
requires_human=True,
)
Read the enum again: the model literally cannot output "clear the hit". Its best case is likely_false_positive routed into your existing four-eyes sanctions process with the discrimination table pre-built. Compliance keeps their process; the process gets faster inputs. That framing is also what makes this deployable at all — you are not asking anyone to approve "AI clears sanctions hits", because it doesn't.
4.2 Repairs — the LLM proposes, the scheme rules decide
Malformed references, truncated beneficiary names, wrong purpose codes: the model is genuinely good at inferring the intended value from context (invoice references in the remittance info, the beneficiary's history, the ordering customer's patterns). But an inferred IBAN is a hallucination risk wearing a fix — so every repair is re-validated deterministically before it becomes a proposal:
class RepairDraft(BaseModel):
field: str # e.g. "beneficiary_iban", "purpose_code"
current_value: str
proposed_value: str
cited_evidence: list[str] # where the proposed value came from
reasoning: str
def validate_repair(draft: RepairDraft, rules: SchemeRules) -> RepairDraft:
if draft.field == "beneficiary_iban":
assert iban_checksum_valid(draft.proposed_value), "repair fails IBAN mod-97 check"
assert country_consistent(draft.proposed_value, rules), "IBAN country vs scheme mismatch"
if draft.field == "purpose_code":
assert draft.proposed_value in rules.allowed_purpose_codes, "unknown purpose code"
assert draft.cited_evidence, "repair cites no evidence"
return draft # only now may it enter a Proposal
A fabricated IBAN fails mod-97 before any human sees it. A purpose code the model "remembered" from training fails the allow-list. The model's creativity is welcome exactly as far as the scheme's arithmetic permits — the same pattern as the reconciliation post's debit-equals-credit check, applied to payment formats.
5. The disposition — release / hold / reject, always gated
Everything converges into a typed disposition proposal:
class Disposition(BaseModel):
recommendation: Literal["release", "hold", "reject"]
repairs: list[RepairDraft] = [] # validated repairs applied on release
cited_evidence: list[str]
rationale: str # the memo the approver reads
confidence: float
async def propose_disposition(state: AgentState) -> Proposal:
d = await opus.ainvoke(
disposition_prompt(state.exception, state.evidence, state.validated_repairs),
response_format=Disposition,
)
return Proposal(
action=d.recommendation,
payload={"payment_id": state.exception.payment.id,
"repairs": [r.model_dump() for r in d.repairs]},
rationale=d.rationale,
confidence=d.confidence,
requires_human=True, # UNCONDITIONAL. Not confidence-gated. Ever.
)
Note what is not here: there is no if confidence > 0.95: requires_human = False. That line is the single most tempting edit in this whole system, it will appear in a code review within a month, and it converts your audit-proof workflow into an autonomous payment engine the first time it's merged. In reconciliation the equivalent shortcut mis-posts a journal you can reverse; here it releases money you may not get back. Hold the line in code review.
The grounding guardian from the reconciliation post runs unchanged: dispositions citing no evidence, or citing evidence IDs not in state, are rejected before the queue.
6. The gate, the clock, and the idempotent release
from langgraph.types import interrupt
async def disposition_node(state: AgentState) -> AgentState:
proposal = state.proposals[-1]
decision = interrupt({ # durable pause — survives restarts
"payment_id": state.exception.payment.id,
"proposal": proposal.model_dump(),
"evidence": [e.summary() for e in state.evidence],
"cutoff_utc": state.cutoff.isoformat(), # approver sees the clock too
"needs": "approve|reject|amend",
})
if decision["action"] != "approve":
return record_rejection(state, proposal, decision)
state.approvals[state.exception.id] = decision["approver"]
# The ONLY write path. Deterministic, idempotent, approval-token-bound.
if proposal.action == "release":
await payments.release(
payment_id=state.exception.payment.id,
repairs=proposal.payload["repairs"],
approval_token=decision["token"], # service verifies token, not caller
idempotency_key=state.exception.id, # retries cannot double-release
)
elif proposal.action == "reject":
await payments.reject(state.exception.payment.id, reason=proposal.rationale,
approval_token=decision["token"])
# "hold" writes a status + a review date; money doesn't move.
return append_audit(state, proposal, result="executed",
extra={"minutes_to_cutoff_at_decision": state.minutes_left()})
Three payment-specific details:
- The release service verifies the approval token itself. Even a bug (or a prompt injection) that reaches this code path with a fabricated proposal cannot release money without a token the approval system minted for this exact payment.
- Idempotency key = exception ID. Graph retries, duplicate resumes, and impatient double-clicks all collapse into one release. Double-release is the payments equivalent of recon's double-posted journal, except the counterparty keeps it.
- The clock goes into the audit log. "Approved with 12 minutes to cut-off" is context a regulator — and your own post-incident review — will want.
7. The payments subgraph
exception (from STP pipeline)
|
v
triage (Haiku label + deterministic clock/priority)
| |
| sanctions_hit | high-value + <30 min
v v
gather_evidence escalate_now (human, evidence-so-far attached)
|
v
assess (Opus): hit discrimination | repair drafts | duplicate narrative
|
v
validate (deterministic): scheme rules, IBAN checksums, duplicate match re-check
|
v
guard (grounding: citations exist and resolve)
|
v
dispose (interrupt() -> human) -> release/reject/hold via tokened service -> signed audit
g = StateGraph(PaymentsState)
g.add_node("triage", triage_node)
g.add_node("gather", gather_evidence)
g.add_node("assess", assess_node)
g.add_node("validate", validate_node)
g.add_node("guard", guard_node)
g.add_node("dispose", disposition_node)
g.add_node("escalate", escalate_node)
g.add_edge(START, "triage")
g.add_conditional_edges("triage",
lambda s: "escalate" if s.escalate_now else "gather")
g.add_edge("gather", "assess")
g.add_edge("assess", "validate")
g.add_conditional_edges("validate",
lambda s: "guard" if s.validations_ok else ("assess" if s.retries < 1 else "escalate"))
g.add_edge("guard", "dispose")
g.add_edge("dispose", END)
g.add_edge("escalate", END)
payments_app = g.compile(checkpointer=postgres_saver)
Same bounded-retry discipline as reconciliation: one re-assess on validation failure, then a human. The clock makes unbounded loops worse here — a wandering agent doesn't just burn tokens, it burns the cut-off.
8. Evals — with one zero-tolerance gate
The golden set is ~200 historical exceptions with analyst dispositions. Three scores run in CI like the reconciliation evals (disposition accuracy, groundedness, narrative quality) — plus one gate with no threshold to tune:
async def eval_payments(golden: list[LabeledException]) -> EvalReport:
report = await run_standard_evals(golden) # accuracy / groundedness / quality
# ZERO-TOLERANCE: on the subset of true sanctions matches (confirmed by compliance),
# the pipeline must never produce recommendation="release". Not 99%. Zero.
true_matches = [c for c in golden if c.confirmed_sanctions_match]
for case in true_matches:
draft = await run_payments_pipeline(case.exception)
assert draft.recommendation != "release", f"RELEASE on true match {case.id} — hard fail"
assert report.disposition_accuracy >= 0.80
assert report.groundedness >= 0.95
return report
If a prompt or model change ever makes that assertion fail, the change doesn't ship, and no aggregate accuracy improvement buys it back. Some regressions are not trade-offs.
9. Representative metrics
| Metric | Manual process | Agentic (propose + approve) |
|---|---|---|
| STP rate | 95-99% | unchanged (pipeline untouched) |
| Handling time per exception | 15-25 min | 3-5 min (review a memo) |
| Exceptions with one-click disposition draft | n/a | ~60-80% |
| Missed cut-offs from queue ordering | FIFO luck | roughly halved (deadline-aware priority) |
| Sanctions false-positive write-up time | 10-20 min | 2-3 min (discrimination pre-drafted) |
| Sanctions decisions made by AI | n/a | zero — structurally |
| Repair format errors reaching humans | analyst catches | rejected by scheme validation first |
| Audit completeness | notes + tribal memory | 100% — signed entry incl. clock state |
Representative of the workflow class, not a single audited deployment — instrument with Langfuse and publish numbers your own auditors can check.
10. The build checklist
- Agent consumes the exception queue only; the STP pipeline is untouched
- Closed exception taxonomy; triage label on a small model
- Urgency computed from scheme cut-offs + clock in code — never by the model
- High-value + low-clock short-circuit to a human with evidence-so-far
- Read-only typed evidence tools; beneficiary history in every investigation
- Sanctions hits: discrimination drafted, decision routed to the existing four-eyes process — no "clear" in the enum
- Repairs re-validated by deterministic scheme rules (IBAN mod-97, BIC, purpose codes)
-
requires_human=Trueunconditional on dispositions; no confidence-gated autonomy, enforced in code review - Release service: approval-token-verified, idempotency-keyed
- Clock state recorded in every audit entry
- Golden set + CI evals, including the zero-tolerance release-on-true-match gate
Honest stuff — when NOT to build this
- Your exception volume is small. A team comfortably clearing 30 exceptions a day doesn't need this; the governance overhead outweighs the minutes saved.
- Your STP rate is poor for fixable reasons. If 15% of payments except because of one upstream format bug, fix the bug — don't buy tokens to investigate self-inflicted exceptions.
- Your sanctions process is in flux. Bolting an agent onto a screening process mid-remediation multiplies the moving parts; stabilize the process, then accelerate it.
- You can't get the beneficiary history. Without historical payment context the drafts degrade to generic reasoning — the acceptance rate won't justify the build.
- You're being sold "autonomous payment operations." Anyone promising unattended release decisions is selling you the exact component this architecture exists to forbid. The human gate is the product, not the limitation.
- Cut-off data is unreliable. Deadline-aware triage with wrong cut-offs is worse than FIFO — it confidently deprioritizes the wrong payments. Verify the reference data first.
- You expect this to raise your STP rate. It won't; it's not in that path. It compresses exception handling. If STP is the goal, that's a different (deterministic) project.
The model to carry forward
The payments agent is the reconciliation agent with two extra disciplines bolted on: a clock that only code may read, and a sanctions wall the model cannot even express a crossing of — no "clear", no "release" in its sanctions vocabulary, dispositions gated by a named human holding a token the release service independently verifies. The LLM does what it's uniquely good at: reading a beneficiary's two-year history, discriminating a fuzzy name match, inferring the intended reference from remittance context — and writing the memo. Money moves only when a person says so, and the audit log can prove it, minute by minute, against the cut-off.
Three habits to keep:
- Watch for the confidence-gate pull request. Someone will propose auto-release above a threshold. Have the refusal written down before they do.
- Feed rejected dispositions to the golden set weekly. Every analyst override is a labeled case; the eval suite should grow faster than the prompt changes.
- Review the clock, not just the decisions. Minutes-to-cutoff-at-decision is your early-warning metric — if it trends down, the queue is saturating before the error rate shows it.
Further reading
- Agentic AI in Finance: How to Automate Regulated Financial Workflows Without Letting an LLM Touch the Money (Real LangGraph Code)
- Agentic AI for Financial Reconciliation: Auto-Explain 80% of Breaks Without Letting the LLM Touch the Ledger (Real LangGraph Code)
- Enterprise AI Security: 7 Attacks on Your LLM App, and the Layer That Stops Them
Building an exceptions agent and want a second set of eyes on the triage matrix, the sanctions routing, or the release gate? I'm always happy to help — reach me at randhir.jassal@gmail.com.
Get the next issue
A short, curated email with the newest posts and questions.