# Payment Dispute & Chargeback Agent

> A card-dispute agent: classifies reason codes, weighs friendly fraud vs. true fraud, and refunds, represents, or escalates — within network rules and refund caps.

- **Category:** Banking & Fintech
- **Difficulty:** Advanced
- **Setup time:** 50 min
- **Stacks:** Claude, LangGraph, OpenAI
- **Version:** 2.0.0 (updated 2026-06-21)
- **Source:** https://agent-kits.com/kit/transaction-dispute-agent

## Overview

Intake → classify → investigate → decide: refund, represent, or escalate — every call grounded in transaction evidence, not a guess.

Distinguishes merchant error, friendly fraud, and true fraud, so legitimate chargebacks are honored and abusive ones are challenged with evidence.

Rule- and timeline-aware: respects card-network reason-code rules and Reg E/Z windows, and never moves money beyond a configured cap without approval.

Defensive on fraud: account-takeover and true-fraud signals trigger escalation and card action, not a silent refund.

## When to use it

- You process card disputes/chargebacks at volume and analysts spend hours on intake, evidence-gathering, and reason-code lookups.
- You have transaction, account, and history data the agent can use to investigate.
- You want consistent, documented dispute handling with a clear audit trail for compliance.
- You want automation to clear the clean cases (obvious merchant errors) and assemble evidence for the contested ones, while routing fraud to humans.

## When not to use it

- You can't give the agent access to transaction/account evidence — it would be deciding blind.
- You want it to make final fraud determinations or move large sums autonomously; those need human analysts.
- Your disputes are dominated by complex litigation or regulatory matters requiring counsel.
- You are unwilling to keep approval gates on refunds above a cap and on representment filings.

## Architecture

- **Dispute intake** — Receives the dispute (from the card processor, banking core, or a form), normalizes amount, merchant, date, and the cardholder's stated reason, and attaches the account reference.
- **Reason-code classification** — Maps the dispute to the correct card-network reason code, which determines the evidence required and the network/regulatory timeline.
- **Evidence retrieval** — Pulls the transaction record, account/dispute history, fraud signals (AVS/CVV, device/IP, velocity), and delivery/usage proof — only what the reason code and hypotheses require.
- **Hypothesis engine** — The model weighs merchant error vs. friendly fraud vs. true fraud against the evidence and produces a confidence and the rationale, citing specific records.
- **Decision & money gate** — A deterministic gate enforces the refund cap, valid-reason requirement, and approval rules; refunds over cap or representment filings are staged for human approval.
- **Evidence assembly** — For representment, compiles the network-required evidence into a structured packet; for fraud, prepares an escalation with card-protection recommendations.
- **Audit & timelines** — Logs the full decision trail with cited evidence and tracks the regulatory/network deadline so nothing ages out; feeds win/loss outcomes back for tuning.

## Files in this bundle

- `system-prompt.md` — the agent's system prompt
- `tools.json` — tool/function definitions the agent expects
- `workflow.md` — step-by-step run loop
- `.env.example` — environment variables to fill in
- `kit.json` — full structured metadata
- `starters/` — minimal starter snippets
- `LICENSE` — Apache-2.0 (code, configuration, and schema)
- `LICENSE-CONTENT` — CC BY 4.0 (specification text and documentation)
- `NOTICE` — attribution and trademark notice
- `run.py` — **runnable demo**: real agent loop with mock tools (`pip install anthropic`, set `ANTHROPIC_API_KEY`, `python run.py`)
- `agentaz.json` / `agentaz.schema.json` — AgentAz™ governance spec + schema

## Implementation notes

- Enforce the refund cap and valid-reason requirement in a deterministic gate; never let the model alone move money. Representment filings stay human-approved by default.
- Treat fraud as a security event: account-takeover and true-fraud signals must escalate with card-protection recommendations, never resolve as a silent refund.
- Require cited evidence for any 'friendly fraud' conclusion. No accusation without specific records; mixed evidence defaults to honoring the dispute.
- Track network/regulatory deadlines on every case (Reg E/Z, network windows). Missing a deadline loses the dispute regardless of merits.
- Backtest against resolved disputes and watch win/loss rate on representments and any wrongly-refunded fraud before enabling auto mode.
- Keep PCI discipline: last-4 only, redact in customer-facing output, and keep evidence within scope.
- A cheaper model can classify reason codes and gather evidence; reserve the strong model for the hypothesis and decision.

## Variations

- **Basic — Dispute triage & evidence assistant:** Classifies the reason code, gathers evidence, and recommends refund/represent/escalate with rationale for an analyst to action. No autonomous money movement.
- **Advanced — Guarded auto-resolution:** Auto-refunds clean, valid disputes within the cap, assembles representment packages for friendly fraud (filed on approval), and escalates fraud — with deadline tracking.
- **Enterprise — Governed disputes operation:** Adds multi-network rule packs, fraud-system integration, full audit and deadline SLAs, representment win-rate analytics, and confidence calibration from outcomes at scale.

## FAQ

**Will it refund disputes automatically?**

Only clean, valid disputes within your configured cap and a recognized reason code. Anything over the cap, outside policy, or showing fraud signals is escalated. Representment filings are human-approved by default.

**How does it tell friendly fraud from a real claim?**

On evidence — delivery confirmation to the verified address, AVS/CVV match, device fingerprint, and prior undisputed usage point to friendly fraud, while their absence supports a genuine claim. It never labels a customer without specific records, and mixed evidence defaults to honoring the dispute.

**What happens if it detects fraud?**

It treats it as a security event: it escalates to your fraud team and recommends protective action (freeze the card, verify the cardholder) rather than refunding a single charge while the account may still be compromised.

**Does it follow card-network and regulatory rules?**

It classifies the correct network reason code, assembles the evidence that code requires, and tracks Reg E/Z and network deadlines so cases don't age out. It won't file a representment without the required evidence.

**Is cardholder data handled safely?**

It keeps PCI discipline — last-4 only, redaction in customer-facing output, and data kept within scope. Sensitive fields are never exposed.

**How do we roll it out?**

Start in assist mode where it recommends and assembles evidence, backtest against resolved disputes, then enable auto-resolution for specific low-risk reason codes within your cap.


---

© 2026 AgentKits · www.agent-kits.com

**Open source.** Code, configuration, and the AgentAz™ schema are licensed under
**Apache-2.0**; specification text and documentation under **CC BY 4.0** (with
attribution to AgentKits, link to https://www.agent-kits.com). See LICENSE, LICENSE-CONTENT,
and NOTICE in this bundle. "AgentAz" and "AgentKits" are trademarks of AgentKits.

**Flagship reference blueprint.** View the source, AgentAz™ spec, and frozen v1.0 schema
in the public registry: https://github.com/agent-kits/agentaz
Original: https://agent-kits.com/kit/transaction-dispute-agent
