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.

Eine Karte ist eine virtuelle Visa, ausgegeben von Ovras reguliertem EU-Banking-Partner. Card-Data (PAN, CVV) ist mit AES-256-GCM at rest verschlüsselt und wird niemals in den Agent-Kontext zurückgegeben — das Modell interagiert ausschließlich mit einem tokenisierten DPAN, der über den Network Token Service derived wird. Multi-Card pro Agent ist ein first-class Konzept. Du kannst innerhalb eines Agents benannte Karten ausgeben (subscriptions, travel, one-off); der Agent wählt pro Transaktion welche.

​
Das Karten-Modell

FeldBeschreibung
idca_*
agentIdAn einen Agent gebunden, immutable
nameEindeutig pro Agent — z.B. default, subs, travel
usagesingle (schließt nach erster Tx) oder multi
statusactive · frozen · terminated
last4Letzte vier Ziffern — sicher zum Anzeigen
brandHeute immer visa
pan_encrypted / cvv_encryptedAES-256-GCM Ciphertext, Server-only

​
Lebenszyklus

StateBedeutung
activeAutorisiert Transaktionen
frozenReversibler Block — POST /cards/:id/unfreeze zum Reaktivieren
terminatedIrreversibel. Neue Karte ausgeben.

​
Operationen

EndpointZweck
POST /cards/agent/:agentIdAusgeben (idempotent) — jede Karte gehört zu genau einem Agent
GET /cards/:cardIdLesen — PAN/CVV nie in Response
GET /cards/agent/:agentId/sensitiveSensitive Reveal (PAN/CVV) — Rate-limited 3/min, audit-logged
POST /cards/:cardId/freeze / /unfreeze / /closeLifecycle (per-Card)
POST /fundOrg-Wallet aufladen (Karten ziehen vom Wallet — kein Card-Level-Funding)
PUT /cards/:cardId/limitsLimits aktualisieren

​
Karte ausgeben

curl -X POST https://api.getovra.com/cards/agent/ag_... \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "agentId": "ag_...",
    "name": "subscriptions",
    "usage": "multi",
    "purpose": "Nur Recurring SaaS",
    "maxTransactionEuros": 250,
    "monthlyLimitEuros": 1000
  }'

​
Karten-Selektion zur Transaktionszeit

Pro Intent eine Karte referenzieren. Entweder cardId oder cardName (innerhalb des Agents). Beide weglassen returnt E_CARD_REQUIRED — es gibt by design keine implizite Default-Karte. 
curl -X POST https://api.getovra.com/intents \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -d '{
    "agentId": "ag_...",
    "cardName": "subscriptions",
    "purpose": "Hetzner verlängern",
    "expectedAmountEuros": 4.51,
    "expectedMerchant": "hetzner.com"
  }'

​
DPAN — der einzige Card-Identifier den der Merchant sieht

Der DPAN (Device Primary Account Number) ist ein Network-Token, ausgegeben vom Visa Tokenization Service durch den Banking-Partner. Er ist:
  • Deterministisch derived von der FPAN
  • Nicht reversibel — nutzlos bei Leak
  • Auto-updates über alle Merchants wenn die zugrundeliegende Karte rotiert wird
Jede MPP-Credential und jeder CUA-Autofill-Token resolviert auf einen DPAN, niemals auf die FPAN.

​
Fill-Tokens (ftok_*)

Internal-only verschlüsselte Wrapper für PAN/CVV/Expiry. Im Credential-Flow verwendet, nie an Agents zurückgegeben. Wenn du ftok_ in deinen Logs siehst, hat unser Sanitizer etwas verpasst — bitte Bug filen.

​
Card-Controls-Sync

Spend-Caps, MCC Allow/Block, Country Allow/Block auf der Policy des Karten-Agents werden auf die card-issuer-native Control-Surface gepusht. Policy ist Source of Truth; der Card-Mirror ist Best-Effort-Projection.

​
Webhooks

EventTrigger
card.issuedNeue Karte provisioniert
card.activatedStatus auf active geflippt
card.frozen / card.unfrozenStatus-Change
card.closedTerminal-Lifecycle
card.rotatedNeue Card-Credentials, alte geschlossen
card.fundedFunds auf Karte bewegt
card.shippedReserviert (heute keine physische Karte)
card.limits_changedLimits aktualisiert
card.details_changedCardholder/Expiry/etc geändert

​
Plan-Tier-Limits

PlanKarten
Free1
Starter10
Business25
EnterpriseUnbegrenzt

​
Weiter

Agents

Der Owner jeder Karte.

Policies

Was jede Karten-Spending steuert.

Bezahlung

Wie eine Karte tatsächlich belastet.

Transaktionen

Der Record den jede erfolgreiche Belastung schreibt.