Glossary - Prava Payments Docs

Same thing, different names

Prava’s surfaces sometimes use different names for the same value. This table is the map:

Concept	REST API	Prava Pay CLI	Prose / Concepts
One-time virtual card number	`token`	`Token`	Payment token (virtual PAN)
One-time security code	`dynamic_cvv`	`Cryptogram`	Single-use CVV
Card expiry for the token	`expiry_month` + `expiry_year`	`Expiry` (`MM/YYYY`)	Token expiry
Payment container	session (`session_id`, `ses_…`)	session (`--session-id`)	Session
Spending permission	mandate (in statuses)	— (handled server-side)	Mandate

The portals

Two portals, two audiences. dashboard.prava.space is the developer console: sign up, create API keys, manage allowed domains, switch to production. pay.prava.space is the Prava Pay dashboard for agent owners: approve agent links, enroll cards, set spending controls. A developer integrating the API only needs the console; an agent owner only needs the Prava Pay dashboard.

Core terms

Term	Definition
Session	The container for one payment: customer + merchant + order, created by `POST /v1/sessions` (or `prava sessions create`). Expires after 15 minutes.
Transaction	A single payment attempt within a session (`addCard` or `savedCard` flow).
Passkey	WebAuthn biometric/device approval (Touch ID, Face ID, security key). Required for every payment; no fallback.
Mandate	A card-network-level spending permission: merchant, amount threshold, frequency (`one_time` today), duration. Prava registers it after passkey approval.
Payment token	The single-use virtual card credentials (number + CVV + expiry) issued against an active mandate: merchant-locked, amount-scoped, short-lived.
Enrollment	Securely collecting and tokenizing a card (via `collectPAN` or a hosted page). Yields an `enrollmentId`.
Agentic commerce enrollment	A card flag (`isAgenticCommerceEnrolled`) enabling AI-initiated purchases with network-level (Visa) merchant/amount locking.
Agent owner	The person/business whose account holds the cards and who approves agents; manages everything at pay.prava.space.
Agent linking	Connecting an agent to an owner’s account: `prava setup` → owner approves in the browser → agent is `active` (or later `revoked`).
Quote / checkout (shopping)	In agentic shopping, a quote locks a price (~15 min) for a discovered product; checkout completes the purchase. See Agentic Shopping.
UCP	Shopify’s Universal Commerce Protocol: product search, catalogs, and quotes across participating merchants. See UCP.
Browser Harness	Prava’s checkout automation: confirms the true final total on the live merchant checkout and pays with the one-time token. See Browser Harness.

Key types

Key	Prefix	Lives	Used for
Publishable key	`pk_test_` / `pk_live_`	Frontend	Initializing the SDK
Secret key	`sk_test_` / `sk_live_`	Backend only	Sessions, results, card management
Session token	—	Per-session	Authenticates in-session operations (SDK/iframe)

Session vs mandate vs credential

Easy to conflate; they nest:

A session (15 min) is the workspace for one payment.
Inside it, passkey approval creates a mandate, the permission (merchant + max amount + duration).
Against the mandate, Prava issues the payment token, the actual single-use card credentials you check out with.

Expiry of one doesn’t imply the others: a token can expire while its mandate is active (getting a new token requires a new invocation), and a mandate can outlive the card-entry window.

​Same thing, different names

​The portals

​Core terms

​Key types

​Session vs mandate vs credential

Same thing, different names

The portals

Core terms

Key types

Session vs mandate vs credential