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

# Transaktionen

> Der unveränderliche Record den jede settled Belastung produziert.

Eine Transaktion ist die Source of Truth für „Geld bewegt". Jede erfolgreiche Belastung — MPP, CUA oder simuliert — schreibt eine `transactions`-Row gebunden an Agent und Intent. Transaktionen sind post-completion immutable; Refunds und Disputes schreiben neue Rows die auf das Original referenzieren.

## Das Transaktions-Modell

| Feld                    | Typ      | Beschreibung                                          |
| ----------------------- | -------- | ----------------------------------------------------- |
| `id`                    | `tx_*`   | Identifier                                            |
| `intentId`              | `int_*`  | Autorisierender Intent (immer present in v1.2)        |
| `agentId`               | `ag_*`   | Owning Agent                                          |
| `cardId`                | `ca_*`   | Belastete Karte                                       |
| `amountEuros`           | number   | EUR-Betrag                                            |
| `currency`              | string   | Immer `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 nach `/intents/:id/verify`                       |
| `mismatch`              | boolean  | True wenn Actual über `amountTolerancePercent` abwich |
| `issuerAuthorizationId` | string?  | Card-Issuer-Auth-Reference                            |
| `issuerSettlementId`    | string?  | Card-Issuer-Settlement-Reference                      |
| `createdAt`             | ISO 8601 | UTC                                                   |

## Lebenszyklus

```text theme={}
pending → completed     (Auth + Settlement OK)
pending → failed        (Decline oder Downstream-Error)
completed → reversed    (Refund applied)
```

Für MPP emittiert die Rail `mpp.transaction.completed` bei Erfolg. Für CUA und Card-Auths siehst du `transaction.authorization` gefolgt von `transaction.settlement`, dann `transaction.completed`.

## Transaktionen auflisten

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

Cursor-paginated. Filter nach 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 gekündigt"
  }'
```

Der Card-Issuer-Webhook treibt die Reversal — wenn settled, flippt der Status der ursprünglichen Transaktion auf `reversed` und `transaction.refunded` feuert.

## Disputes

Siehe [Disputes](/de/concepts/disputes). Eine Transaktion kann maximal einen offenen Dispute haben. Disputes tragen Evidence (Receipt, Shipping, Communication etc.) und einen Status-FSM.

## Memos und Comments

```bash theme={}
# Memo hinzufügen (single Field, ersetzt existierendes)
curl -X PATCH https://api.getovra.com/transactions/tx_.../memo \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -d '{ "memo": "Q2-Marketing-Budget" }'

# Comment anhängen (audit-logged)
curl -X POST https://api.getovra.com/transactions/tx_.../comments \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -d '{ "comment": "Von Finance reviewed" }'
```

## Webhooks

| Event                       | Wann                               |
| --------------------------- | ---------------------------------- |
| `transaction.created`       | Row inserted                       |
| `transaction.authorization` | Card-Auth akzeptiert               |
| `transaction.settlement`    | Karte gecleart                     |
| `transaction.completed`     | Final State — Auth + Settlement OK |
| `transaction.declined`      | Authorization abgelehnt            |
| `transaction.settled`       | Settled (legacy Alias)             |
| `transaction.updated`       | Memo oder Status geändert          |
| `transaction.refunded`      | Refund gepostet                    |
| `mpp.transaction.completed` | MPP-Rail-Settle                    |
| `verification.mismatch`     | Actual divergierte über Toleranz   |

## Plan-Tier-History-Retention

| Plan       | History  |
| ---------- | -------- |
| Free       | 30 Tage  |
| Starter    | 90 Tage  |
| Business   | 365 Tage |
| Enterprise | 5 Jahre  |

Ältere Transaktionen werden automatisch gepruned; Export via `/audit/export` für Long-Term-Retention.

## Surfaces

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

## Weiter

<CardGroup cols={2}>
  <Card title="Disputes" icon="gavel" href="/de/concepts/disputes">
    Eine Transaktion anfechten.
  </Card>

  <Card title="Intelligenz" icon="chart-line" href="/de/concepts/intelligence">
    Analytics, Anomaly-Detection, Audit über Transaktionen.
  </Card>

  <Card title="Webhooks" icon="bell" href="/de/concepts/webhooks">
    In Echtzeit auf Transaction-Events reagieren.
  </Card>
</CardGroup>