Zum Hauptinhalt springen

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

FeldBeschreibung
idpr_*
destinationWalletIdWo das Geld landet
amountEurosEUR-Betrag, ≤ 1.000.000
descriptionFreitext; sichtbar in der Payer-View
counterpartyOwnerIdGesetzt für interne Requests (anderer Ovra-Kunde)
sepaInstructions{ iban, bic, reference } für externe Requests; Reference ist OVRA-PR-<hex>
payerName / payerEmailOptional — zeigt sich auf der Payer-Seite
agentIdOptional — Request an einen Agent binden
expiresAtOptional TTL (max. 30 Tage)
statuspending → paid · expired · cancelled

​
Operationen

EndpointZweck
POST /claim/requestsRequest erstellen. counterpartyOwnerId für intern, weglassen für extern.
GET /claim/requestsEigene Requests auflisten. Filter status, inbound=true für Payer-View.
GET /claim/requests/:idDetail — Owner oder Counterparty erlaubt.
POST /claim/requests/:id/settleNur intern. Atomarer Wallet→Wallet-Debit/Credit + Ledger + Transfer-Row.
POST /claim/requests/:id/cancelUnbezahlten 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"
  }'
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

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.

​
Surfaces

SurfaceStatus
REST APIVoll
SDK (@ovra/sdk)ovra.collect.*
MCPovra_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.