> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getovra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Disputes

> File and resolve chargebacks against agent transactions.

A dispute is a formal challenge against a settled transaction. Useful when goods don't arrive, the merchant overcharges, or the agent paid for something unauthorized despite the policy. Each transaction can have at most one open dispute. Dispute lifecycle is plan-tier-gated.

## Reason codes

| Code                   | Meaning                               |
| ---------------------- | ------------------------------------- |
| `unauthorized`         | Spend wasn't authorized by policy     |
| `fraud`                | Suspected fraudulent transaction      |
| `not_received`         | Goods or service never delivered      |
| `not_as_described`     | Delivered but doesn't match agreement |
| `duplicate`            | Charged more than once                |
| `incorrect_amount`     | Amount differs from agreed price      |
| `canceled`             | Cancelled but still charged           |
| `credit_not_processed` | Refund wasn't applied                 |

## File a dispute

```bash theme={}
curl -X POST https://api.getovra.com/disputes \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "transactionId": "tx_...",
    "reason": "not_received",
    "description": "Order placed 10 days ago, tracking shows no movement"
  }'
```

Response:

```json theme={}
{
  "id": "dsp_...",
  "transactionId": "tx_...",
  "reason": "not_received",
  "status": "open",
  "createdAt": "2026-04-20T12:34:56Z"
}
```

## Attach evidence

```bash theme={}
curl -X POST https://api.getovra.com/disputes/dsp_.../evidence \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "communication",
    "description": "Email thread with merchant support",
    "fileUrl": "https://storage.example.com/evidence/abc.pdf"
  }'
```

Evidence types: `receipt` · `shipping` · `communication` · `cancellation` · `refund_policy` · `product_description` · `other`. File URLs must be HTTPS and SSRF-safe (no private IPs).

## Resolve

```bash theme={}
curl -X PATCH https://api.getovra.com/disputes/dsp_... \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -d '{ "status": "resolved" }'
```

Set status to `resolved` or `rejected`. Once closed, no further mutation is allowed.

## Webhooks

| Event              | When                             |
| ------------------ | -------------------------------- |
| `dispute.created`  | Filed                            |
| `dispute.updated`  | Evidence added or fields changed |
| `dispute.resolved` | Closed (resolved or rejected)    |

## Plan-tier gating

| Plan       | Dispute management             |
| ---------- | ------------------------------ |
| Free       | –                              |
| Starter    | View only                      |
| Business   | Full (file + manage + resolve) |
| Enterprise | Full + automated workflows     |

## Surfaces

| Surface   | Capability                              |
| --------- | --------------------------------------- |
| REST      | `/disputes`, `/disputes/:id/evidence`   |
| SDK       | `ovra.disputes.*`                       |
| MCP       | `ovra_dispute` (action: `get` · `file`) |
| Dashboard | `/dashboard/disputes`                   |

## Next

<CardGroup cols={2}>
  <Card title="Transactions" icon="receipt" href="/concepts/transactions">
    What you're disputing.
  </Card>

  <Card title="Intelligence" icon="chart-line" href="/concepts/intelligence">
    Audit trail and access events for dispute investigations.
  </Card>
</CardGroup>