Karten

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

Feld	Beschreibung
`id`	`ca_*`
`agentId`	An einen Agent gebunden, immutable
`name`	Eindeutig pro Agent — z.B. `default`, `subs`, `travel`
`usage`	`single` (schließt nach erster Tx) oder `multi`
`status`	`active` · `frozen` · `terminated`
`last4`	Letzte vier Ziffern — sicher zum Anzeigen
`brand`	Heute immer `visa`
`pan_encrypted` / `cvv_encrypted`	AES-256-GCM Ciphertext, Server-only

Lebenszyklus

State	Bedeutung
`active`	Autorisiert Transaktionen
`frozen`	Reversibler Block — `POST /cards/:id/unfreeze` zum Reaktivieren
`terminated`	Irreversibel. Neue Karte ausgeben.

Operationen

Endpoint	Zweck
`POST /cards/agent/:agentId`	Ausgeben (idempotent) — jede Karte gehört zu genau einem Agent
`GET /cards/:cardId`	Lesen — PAN/CVV nie in Response
`GET /cards/agent/:agentId/sensitive`	Sensitive Reveal (PAN/CVV) — Rate-limited 3/min, audit-logged
`POST /cards/:cardId/freeze` / `/unfreeze` / `/close`	Lifecycle (per-Card)
`POST /fund`	Org-Wallet aufladen (Karten ziehen vom Wallet — kein Card-Level-Funding)
`PUT /cards/:cardId/limits`	Limits 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
  }'

const card = await ovra.cards.create({
  agentId: "ag_...",
  name: "subscriptions",
  usage: "multi",
  purpose: "Nur Recurring SaaS",
  maxTransactionEuros: 250,
  monthlyLimitEuros: 1000,
});

ovra_card { action: "issue", agentId: "ag_...", usage: "multi", purpose: "Nur Recurring SaaS" }

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

Event	Trigger
`card.issued`	Neue Karte provisioniert
`card.activated`	Status auf `active` geflippt
`card.frozen` / `card.unfrozen`	Status-Change
`card.closed`	Terminal-Lifecycle
`card.rotated`	Neue Card-Credentials, alte geschlossen
`card.funded`	Funds auf Karte bewegt
`card.shipped`	Reserviert (heute keine physische Karte)
`card.limits_changed`	Limits aktualisiert
`card.details_changed`	Cardholder/Expiry/etc geändert

Plan-Tier-Limits

Plan	Karten
Free	1
Starter	10
Business	25
Enterprise	Unbegrenzt

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.

Erste Schritte

Die sechs Säulen

Kern-Primitive

Zahlungsmodi

Plattform

Das Karten-Modell

Lebenszyklus

Operationen

Karte ausgeben

Karten-Selektion zur Transaktionszeit

DPAN — der einzige Card-Identifier den der Merchant sieht

Fill-Tokens (`ftok_*`)

Card-Controls-Sync

Webhooks

Plan-Tier-Limits

Weiter

Agents

Policies

Bezahlung

Transaktionen

​Das Karten-Modell

​Lebenszyklus

​Operationen

​Karte ausgeben

​Karten-Selektion zur Transaktionszeit

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

​Fill-Tokens (ftok_*)

​Card-Controls-Sync

​Webhooks

​Plan-Tier-Limits

​Weiter

Agents

Policies

Bezahlung

Transaktionen

Das Karten-Modell

Lebenszyklus

Operationen

Karte ausgeben

Karten-Selektion zur Transaktionszeit

DPAN — der einzige Card-Identifier den der Merchant sieht

Fill-Tokens (`ftok_*`)

Card-Controls-Sync

Webhooks

Plan-Tier-Limits

Weiter