Skip to main content

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.

A card is a virtual Visa issued by Ovra’s regulated EU banking partner. Card data (PAN, CVV) is encrypted with AES-256-GCM at rest and never returned to the agent’s context — the model only ever interacts with a tokenized DPAN derived through the network token service. Multi-card per agent is a first-class concept. You can issue named cards within a single agent (subscriptions, travel, one-off) and the agent picks which one to charge for each transaction.

​
The card model

FieldDescription
idca_*
agentIdBound to one agent, immutable
nameUnique per agent — e.g. default, subs, travel
usagesingle (closes after first tx) or multi
statusactive · frozen · terminated
last4Last four digits — safe to display
brandAlways visa today
pan_encrypted / cvv_encryptedAES-256-GCM ciphertext, server-only

​
Lifecycle

StateMeaning
activeAuthorizes transactions
frozenReversible block — POST /cards/:id/unfreeze to resume
terminatedIrreversible. Issue a new card.

​
Operations

EndpointPurpose
POST /cards/agent/:agentIdIssue (idempotent) — every card belongs to exactly one agent
GET /cards/:cardIdRead — PAN/CVV never 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 /fundTop-up the org wallet (cards draw from wallet — no card-level funding)
PUT /cards/:cardId/limitsUpdate spending limits

​
Issue a card

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": "Recurring SaaS only",
    "maxTransactionEuros": 250,
    "monthlyLimitEuros": 1000
  }'

​
Card selection at transaction time

Reference a card on every intent. Pass either cardId or cardName (within the agent). Omitting both returns E_CARD_REQUIRED — there is no implicit default card by design. 
curl -X POST https://api.getovra.com/intents \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -d '{
    "agentId": "ag_...",
    "cardName": "subscriptions",
    "purpose": "Renew Hetzner",
    "expectedAmountEuros": 4.51,
    "expectedMerchant": "hetzner.com"
  }'

​
DPAN — the only card identifier the merchant sees

The DPAN (Device Primary Account Number) is a network token issued by Visa’s tokenization service through the banking partner. It’s:
  • Deterministically derived from the FPAN
  • Non-reversible — useless if leaked
  • Auto-updates across merchants when the underlying card is rotated
Every MPP credential and CUA autofill token resolves to a DPAN, never the FPAN.

​
Fill tokens (ftok_*)

Internal-only encrypted wrappers for PAN/CVV/expiry. Used inside the credential flow, never returned to agents. If you see ftok_ in your logs, our sanitizer missed something — file a bug.

​
Card-controls sync

Spend caps, MCC allow/block, country allow/block on the policy attached to the card’s agent are pushed to the card-issuer-native control surface. Policy is the source of truth; the card mirror is a best-effort projection.

​
Webhooks

EventTrigger
card.issuedNew card provisioned
card.activatedCard status flipped to active
card.frozen / card.unfrozenStatus change
card.closedTerminal lifecycle
card.rotatedNew card credentials issued, old one closed
card.fundedFunds moved onto the card
card.shippedReserved (no physical card today)
card.limits_changedLimits updated
card.details_changedCardholder/expiry/etc updated

​
Plan-tier limits

PlanCards
Free1
Starter10
Business25
EnterpriseUnlimited

​
Next

Agents

The owner of every card.

Policies

What governs each card’s spending.

Pay

How a card actually charges.

Transactions

The record every successful charge writes.