# Setup guide — Payment Dispute & Chargeback Agent

## 1. Install and connect data sources

Install the agent and connect it (read access) to your processor/banking core and fraud signals.

```
pipx install disputes-agent
disputes-agent connect --processor stripe --core finxact --fraud sift
disputes-agent doctor
```

## 2. Configure money limits and mode

Caps and approval rules live in config and are enforced deterministically, not by the model.

```
cp .env.example .env
ANTHROPIC_API_KEY=sk-ant-...
AUTO_REFUND_CAP_USD=100
MAX_TOOL_CALLS=8
MODE=assist   # assist (recommend) | act (auto within cap)
```

## 3. Map reason codes and deadlines

Provide the network reason-code rules and timelines you operate under so evidence and deadlines are correct.

```
# .disputes.yml
networks: [visa, mastercard]
auto_refund_reasons: ["duplicate_processing", "credit_not_processed"]
track_deadlines: true
fraud_escalate_signals: ["account_takeover", "device_mismatch", "velocity_spike"]
```

## 4. Backtest on resolved disputes

Replay closed disputes to compare the agent's decisions to actual outcomes before going live.

```
disputes-agent backtest --range 90d --explain
# reports refund/represent/escalate accuracy vs. final outcomes
```

## 5. Wire into your dispute queue

Route new disputes to the agent. Start in assist mode (recommends), then enable act mode for low-risk reason codes within the cap.

```
# webhook: new dispute -> POST https://your-host/disputes/intake (HMAC)
# promote MODE=act for e.g. duplicate_processing once backtests look clean
```
