Skip to main content
Cards belong to an identity — any number per identity. A card is prepaid: bought once for a load between the bounds the quote reports (1to1 to 150), paid for from the organization’s credits before the issuer is asked, and never reloaded. An agent can see and use a card only when its session selected the identity that owns it; there is no separate card-to-agent assignment — the identity grant is the assignment.

​
Lifecycle

  1. Price a load with POST /v1/identities/{id}/cards/quote. The quote is the load plus the issuer’s fee, in micro-USD (50 USD load → e.g. 50500000 price).
  2. Buy the card with POST /v1/identities/{id}/cards. Credits are debited first; a short balance answers insufficient_credits and nothing is ordered. The card is issuing until the issuer fulfils, then active — reading an issuing card asks the issuer for its current state.
  3. Reveal the number and PIN with GET /v1/identities/{id}/cards/{cid}/credentials — the one route that returns them. Every reveal is audited and never cached.
  4. Log spend against the card with POST /v1/identities/{id}/cards/{cid}/transactions; the card refuses a spend that would exceed its load. A prepaid card has no live authorization feed; this ledger is what the identity and its agents record.
Credentials live in a table no list or detail read joins; the card object carries brand and last4 only. cancel retires an active card locally; refund returns the credits of a card the issuer never delivered; retry re-runs a failed issuance on the same debit.

​
Agent tools

The three ask tools go through the ordinary human-in-the-loop proposal: the session pauses on the proposal and the operator approves or declines it, exactly as for any other guarded tool mutation. retry and refund are operator actions with no agent tool.

​
In a blueprint

naive up matches by label: a live (pending_payment, issuing or active) card with that label is unchanged; a missing or spent-out (failed, cancelled, refunded) one is issued. naive up --dry-run quotes instead of issuing and reports the credits it would debit.

​
What this replaces

Earlier card programs offered a managed virtual card with a cardholder, top-ups, and an external checkout for funding. Vetta ships the prepaid card only: funding is the organization’s credits (no checkout, no payment polling), a card is loaded once (no top-up — issue another), and the cardholder and managed-card program are not part of the launch. Assigning a card to an agent is replaced by the identity grant.

Cards API

Quote, issue, reveal, cancel, refund and log spend.