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

# Einzug (Collect)

> Zahlungen für Arbeit einziehen, die deine Agents geliefert haben.

Einzug schließt den Loop für agenten-native Ökonomien — dein Agent gibt nicht nur aus, er kann auch einnehmen. Erstelle einen Payment-Request und die Gegenpartei zahlt aus einem anderen Ovra-Wallet (instant, kostenlos) oder via SEPA mit Reference-Matching (extern).

<Note>
  **Intern Ovra-zu-Ovra funktioniert heute.** Externer SEPA-Inbound-Match ist auf der Roadmap und wird derzeit vom `/settle`-Endpoint abgelehnt. Status-Tabelle siehe unten.
</Note>

## Warum das wichtig ist

Wenn dein Agent Arbeit erledigt, für die jemand anderes bezahlt — Services, Waren, Microtransactions, API-Calls — brauchst du einen Weg zum Einziehen. Ohne Einzug ist „Agent Payments" eine Einbahnstraße. Mit ihm können Agents Geschäfte betreiben.

## Das Payment-Request-Modell

| Feld                       | Beschreibung                                                                       |
| -------------------------- | ---------------------------------------------------------------------------------- |
| `id`                       | `pr_*`                                                                             |
| `destinationWalletId`      | Wo das Geld landet                                                                 |
| `amountEuros`              | EUR-Betrag, ≤ 1.000.000                                                            |
| `description`              | Freitext; sichtbar in der Payer-View                                               |
| `counterpartyOwnerId`      | Gesetzt für **interne** Requests (anderer Ovra-Kunde)                              |
| `sepaInstructions`         | `{ iban, bic, reference }` für **externe** Requests; Reference ist `OVRA-PR-<hex>` |
| `payerName` / `payerEmail` | Optional — zeigt sich auf der Payer-Seite                                          |
| `agentId`                  | Optional — Request an einen Agent binden                                           |
| `expiresAt`                | Optional TTL (max. 30 Tage)                                                        |
| `status`                   | `pending → paid · expired · cancelled`                                             |

## Operationen

| Endpoint                          | Zweck                                                                        |
| --------------------------------- | ---------------------------------------------------------------------------- |
| `POST /claim/requests`            | Request erstellen. `counterpartyOwnerId` für intern, weglassen für extern.   |
| `GET /claim/requests`             | Eigene Requests auflisten. Filter `status`, `inbound=true` für Payer-View.   |
| `GET /claim/requests/:id`         | Detail — Owner oder Counterparty erlaubt.                                    |
| `POST /claim/requests/:id/settle` | **Nur intern.** Atomarer Wallet→Wallet-Debit/Credit + Ledger + Transfer-Row. |
| `POST /claim/requests/:id/cancel` | Unbezahlten Request stornieren.                                              |
| `GET /claim/requests/:id/pay`     | Öffentliche Payer-Seite — kein Auth nötig.                                   |

<Note>
  Die Säule heißt **Einzug** aber die Routes laufen weiterhin unter `/claim/*`. Der Route-Rename ist anstehende Tech-Debt; der URL-Vertrag ist stabil.
</Note>

## Request erstellen

<CodeGroup>
  ```bash curl theme={}
  curl -X POST https://api.getovra.com/claim/requests \
    -H "Authorization: Bearer $OVRA_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $(uuidgen)" \
    -d '{
      "destinationWalletId": "wal_...",
      "amountEuros": 49.00,
      "description": "Recherche-Bericht — 3 Quellen",
      "payerEmail": "ops@acme.example"
    }'
  ```

  ```ts SDK theme={}
  const req = await ovra.collect.create({
    destinationWalletId: "wal_...",
    amountEuros: 49,
    description: "Recherche-Bericht — 3 Quellen",
    payerEmail: "ops@acme.example",
  });
  ```
</CodeGroup>

Response:

```json theme={}
{
  "id": "pr_...",
  "amountEuros": 49,
  "status": "pending",
  "settlementType": "external",
  "sepaInstructions": {
    "iban": "DE89370400440000001234",
    "bic": "PLINDE21",
    "reference": "OVRA-PR-a3f9b1c2"
  },
  "expiresAt": "2026-05-20T10:00:00Z"
}
```

## Settle-Pfad-Matrix

<Tabs>
  <Tab title="Intern (Ovra → Ovra)">
    Counterparty hat ein Ovra-Wallet. `counterpartyOwnerId` im Create-Call übergeben. Counterparty ruft `POST /claim/requests/:id/settle` mit `sourceWalletId`. Debit und Credit in einer Transaktion:

    * SQL `BEGIN`
    * `UPDATE wallets SET balance_euros = balance_euros - amount WHERE id = :src AND balance_euros >= amount`
    * `UPDATE wallets SET balance_euros = balance_euros + amount WHERE id = :dst`
    * INSERT `ledger_entries` (Debit + Credit), `transfers`-Row, Request `paid` setzen
    * `COMMIT`
    * `claim.request.paid` Webhook feuern

    Ergebnis: instant, kostenlos, voll auditierbar. ✅ Production-ready.
  </Tab>

  <Tab title="Extern (SEPA-Inbound)">
    Counterparty ist außerhalb Ovras. Der Request returnt `sepaInstructions` mit einer `OVRA-PR-<hex>`-Reference. Der Payer initiiert SEPA mit dieser Reference.

    ⚠️ **Aktuell TODO.** `/settle` lehnt externe Requests heute ab (kein SEPA-In-Reconciliation-Pipeline). Entscheidungsoptionen:

    1. Dedizierten SEPA-In-Provider für Reference-Matching integrieren.
    2. Banking-Partner SEPA-Inbound-Feed nutzen (v1.3+ Live-Mode).
    3. Manueller Operator-Match im Dashboard für die Demo-Phase.
  </Tab>
</Tabs>

## Surfaces

| Surface           | Status                                                                                                |
| ----------------- | ----------------------------------------------------------------------------------------------------- |
| REST API          | Voll                                                                                                  |
| SDK (`@ovra/sdk`) | `ovra.collect.*`                                                                                      |
| MCP               | `ovra_claim` (action-multiplexed) — Tool-Name wird in einem zukünftigen MCP-Release zu `ovra_collect` |
| Dashboard         | `/dashboard/collect` — Create-Drawer, Filter-Liste, Detail-Drawer                                     |

## Webhooks

Diese Events abonnieren, um in Echtzeit zu reagieren:

* `claim.request.created`
* `claim.request.paid`
* `claim.request.expired`
* `claim.request.cancelled`

Siehe [Webhooks](/de/concepts/webhooks) für Delivery, Retries und Signaturverifikation.

## Weiter

<CardGroup cols={2}>
  <Card title="Konten" icon="wallet" href="/de/concepts/accounts">
    Wallets, IBANs, Transfers — wo das Geld liegt.
  </Card>

  <Card title="Webhooks" icon="bell" href="/de/concepts/webhooks">
    Fire-and-forget Delivery für `claim.request.*` Events.
  </Card>
</CardGroup>