Cards

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

Field	Description
`id`	`ca_*`
`agentId`	Bound to one agent, immutable
`name`	Unique per agent — e.g. `default`, `subs`, `travel`
`usage`	`single` (closes after first tx) or `multi`
`status`	`active` · `frozen` · `terminated`
`last4`	Last four digits — safe to display
`brand`	Always `visa` today
`pan_encrypted` / `cvv_encrypted`	AES-256-GCM ciphertext, server-only

Lifecycle

State	Meaning
`active`	Authorizes transactions
`frozen`	Reversible block — `POST /cards/:id/unfreeze` to resume
`terminated`	Irreversible. Issue a new card.

Operations

Endpoint	Purpose
`POST /cards/agent/:agentId`	Issue (idempotent) — every card belongs to exactly one agent
`GET /cards/:cardId`	Read — PAN/CVV never 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`	Top-up the org wallet (cards draw from wallet — no card-level funding)
`PUT /cards/:cardId/limits`	Update 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
  }'

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

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

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

Event	Trigger
`card.issued`	New card provisioned
`card.activated`	Card status flipped to `active`
`card.frozen` / `card.unfrozen`	Status change
`card.closed`	Terminal lifecycle
`card.rotated`	New card credentials issued, old one closed
`card.funded`	Funds moved onto the card
`card.shipped`	Reserved (no physical card today)
`card.limits_changed`	Limits updated
`card.details_changed`	Cardholder/expiry/etc updated

Plan-tier limits

Plan	Cards
Free	1
Starter	10
Business	25
Enterprise	Unlimited

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.

Getting Started

The Six Pillars

Core Primitives

Payment Modes

Platform

The card model

Lifecycle

Operations

Issue a card

Card selection at transaction time

DPAN — the only card identifier the merchant sees

Fill tokens (`ftok_*`)

Card-controls sync

Webhooks

Plan-tier limits

Next

Agents

Policies

Pay

Transactions

​The card model

​Lifecycle

​Operations

​Issue a card

​Card selection at transaction time

​DPAN — the only card identifier the merchant sees

​Fill tokens (ftok_*)

​Card-controls sync

​Webhooks

​Plan-tier limits

​Next

Agents

Policies

Pay

Transactions

The card model

Lifecycle

Operations

Issue a card

Card selection at transaction time

DPAN — the only card identifier the merchant sees

Fill tokens (`ftok_*`)

Card-controls sync

Webhooks

Plan-tier limits

Next