Einzug (Collect)

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

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.

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.

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.

Request erstellen

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"
  }'

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

Response:

{
  "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

Intern (Ovra → Ovra)
Extern (SEPA-Inbound)

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.

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:

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

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 für Delivery, Retries und Signaturverifikation.

Weiter

Konten

Wallets, IBANs, Transfers — wo das Geld liegt.

Webhooks

Fire-and-forget Delivery für claim.request.* Events.

Erste Schritte

Die sechs Säulen

Kern-Primitive

Zahlungsmodi

Plattform

Einzug (Collect)

Warum das wichtig ist

Das Payment-Request-Modell

Operationen

Request erstellen

Settle-Pfad-Matrix

Surfaces

Webhooks

Weiter

Konten

Webhooks

​Warum das wichtig ist

​Das Payment-Request-Modell

​Operationen

​Request erstellen

​Settle-Pfad-Matrix

​Surfaces

​Webhooks

​Weiter

Konten

Webhooks

Warum das wichtig ist

Das Payment-Request-Modell

Operationen

Request erstellen

Settle-Pfad-Matrix

Surfaces

Webhooks

Weiter