> ## 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.

# Transactions

> The immutable record every settled charge produces.

A transaction is the source of truth for "money moved". Every successful charge — MPP, CUA, or simulated — writes a `transactions` row tied to its agent and intent. Transactions are immutable post-completion; refunds and disputes write new rows that reference the original.

## The transaction model

| Field                   | Type     | Description                                             |
| ----------------------- | -------- | ------------------------------------------------------- |
| `id`                    | `tx_*`   | Identifier                                              |
| `intentId`              | `int_*`  | Authorizing intent (always present in v1.2)             |
| `agentId`               | `ag_*`   | Owning agent                                            |
| `cardId`                | `ca_*`   | Card charged                                            |
| `amountEuros`           | number   | EUR amount                                              |
| `currency`              | string   | Always `EUR`                                            |
| `merchant`              | string   | Merchant name                                           |
| `merchantMcc`           | string   | MCC code                                                |
| `merchantCountry`       | string   | ISO 3166-1 alpha-2                                      |
| `rail`                  | enum     | `mpp` · `cua` · `simulate`                              |
| `status`                | enum     | `pending` → `completed` · `failed` · `reversed`         |
| `verified`              | boolean  | True after `/intents/:id/verify`                        |
| `mismatch`              | boolean  | True if actual deviated beyond `amountTolerancePercent` |
| `issuerAuthorizationId` | string?  | Card-issuer authorization ref                           |
| `issuerSettlementId`    | string?  | Card-issuer settlement ref                              |
| `createdAt`             | ISO 8601 | UTC                                                     |

## Lifecycle

```text theme={}
pending → completed     (auth + settlement OK)
pending → failed        (declined or downstream error)
completed → reversed    (refund applied)
```

For MPP, the rail emits `mpp.transaction.completed` on success. For CUA and card auths, you'll see `transaction.authorization` followed by `transaction.settlement`, then `transaction.completed`.

## List transactions

```bash theme={}
curl "https://api.getovra.com/transactions?agentId=ag_...&limit=50" \
  -H "Authorization: Bearer $OVRA_API_KEY"
```

Cursor-paginated. Supports filters by agent, card, intent, merchant, status, date range.

## Refunds

```bash theme={}
curl -X POST https://api.getovra.com/refunds \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "transactionId": "tx_...",
    "amountEuros": 4.51,
    "reason": "Subscription cancelled"
  }'
```

The card issuer's webhook drives the actual reversal — when settled, the original transaction's `status` flips to `reversed` and `transaction.refunded` fires.

## Disputes

See [Disputes](/concepts/disputes). One transaction can have at most one open dispute. Disputes carry evidence (receipt, shipping, communication, etc.) and a status FSM.

## Memos and comments

```bash theme={}
# Add a memo (single field, replaces existing)
curl -X PATCH https://api.getovra.com/transactions/tx_.../memo \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -d '{ "memo": "Q2 marketing budget" }'

# Append a comment (audit-logged)
curl -X POST https://api.getovra.com/transactions/tx_.../comments \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -d '{ "comment": "Reviewed by finance" }'
```

## Webhooks

| Event                       | When                                         |
| --------------------------- | -------------------------------------------- |
| `transaction.created`       | Row inserted                                 |
| `transaction.authorization` | Card auth accepted                           |
| `transaction.settlement`    | Card cleared                                 |
| `transaction.completed`     | Final state — auth + settlement OK           |
| `transaction.declined`      | Authorization declined                       |
| `transaction.settled`       | Settled (legacy alias)                       |
| `transaction.updated`       | Memo or status changed                       |
| `transaction.refunded`      | Refund posted                                |
| `mpp.transaction.completed` | MPP-rail settle                              |
| `verification.mismatch`     | Actual diverged from intent beyond tolerance |

## Plan-tier history retention

| Plan       | History  |
| ---------- | -------- |
| Free       | 30 days  |
| Starter    | 90 days  |
| Business   | 365 days |
| Enterprise | 5 years  |

Older transactions are pruned automatically; export via `/audit/export` for long-term retention.

## Surfaces

| Surface   | Capability                                       |
| --------- | ------------------------------------------------ |
| REST      | `/transactions`, `/transactions/:id`, `/refunds` |
| SDK       | `ovra.transactions.*`, `ovra.refunds.*`          |
| MCP       | `ovra_transaction` (read + memo)                 |
| Dashboard | `/dashboard/activity` (consolidated view)        |

## Next

<CardGroup cols={2}>
  <Card title="Disputes" icon="gavel" href="/concepts/disputes">
    Challenge a transaction.
  </Card>

  <Card title="Intelligence" icon="chart-line" href="/concepts/intelligence">
    Analytics, anomaly detection, audit on top of transactions.
  </Card>

  <Card title="Webhooks" icon="bell" href="/concepts/webhooks">
    React to transaction events in real time.
  </Card>
</CardGroup>