Quickstart

This walkthrough takes you from zero to a settled sandbox transaction. You will create an account, reveal your API key, register the MCP server, create an agent and a card, declare an intent, and simulate a charge.

Everything in this quickstart runs in sandbox. Card numbers, IBANs, and webhooks are live-shaped but no real money moves.

Request a sandbox invite at getovra.com/sign-up. Once accepted, sign in — your sandbox organization, IBAN, default policy, and API key are auto-provisioned.

The reveal modal shows your sk_sandbox_* key once. Copy it now. You can rotate it later via Dashboard → API Keys.

export OVRA_API_KEY="sk_sandbox_..."

Connect the MCP server (optional)

The MCP server gives any LLM client (Claude Desktop, Cursor, Kiro, etc.) all 19 Ovra tools.

{
  "mcpServers": {
    "ovra": {
      "command": "npx",
      "args": ["@ovra/mcp@latest"],
      "env": { "OVRA_API_KEY": "sk_sandbox_..." }
    }
  }
}

{
  "mcpServers": {
    "ovra": {
      "type": "streamable-http",
      "url": "https://api.getovra.com/api/mcp",
      "headers": { "Authorization": "Bearer sk_sandbox_..." }
    }
  }
}

Restart your client. You should see 19 ovra_* tools. See MCP setup for advanced configuration.

Create an agent

An agent is a first-class entity — it owns cards, tokens, transactions, and a policy. The minimum form is name + purpose + policyId.

curl -X POST https://api.getovra.com/agents \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "procurement-bot",
    "policyId": "po_default_...",
    "profile": { "purpose": "Buy office supplies under EUR 100" }
  }'

import { Ovra } from "@ovra/sdk";
const ovra = new Ovra({ apiKey: process.env.OVRA_API_KEY });

const agent = await ovra.agents.create({
  name: "procurement-bot",
  policyId: "po_default_...",
  profile: { purpose: "Buy office supplies under EUR 100" },
});

Use ovra_agent with action "provision",
  name: "procurement-bot",
  policyId: "po_default_...",
  profile: { purpose: "Buy office supplies under EUR 100" }

Returns { id: "ag_...", status: "active", ... }.

Issue a card for the agent

Each card is bound to one agent and named uniquely within that agent. You can issue multiple cards per agent (subscriptions, travel, one-off).

curl -X POST https://api.getovra.com/cards \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "agentId": "ag_...",
    "name": "default",
    "usage": "multi",
    "purpose": "Default card for procurement"
  }'

Returns { id: "ca_...", last4: "4242", status: "active", ... }. PAN and CVV are encrypted with AES-256-GCM at rest and never returned in plain text on this endpoint.

Declare an intent

No money moves without an approved intent. The policy engine and risk engine run during this call.

curl -X POST https://api.getovra.com/intents \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "agentId": "ag_...",
    "cardId": "ca_...",
    "purpose": "Pack of USB-C hubs",
    "expectedAmountEuros": 29.99,
    "expectedMerchant": "amazon.de"
  }'

If the policy auto-approves, you get back { status: "approved" }. Otherwise pending_approval — approve from the dashboard or POST /intents/:id/approve.

Simulate a charge

In sandbox you can shortcut the merchant call:

curl -X POST https://api.getovra.com/simulate/charge \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "intentId": "int_...",
    "amountEuros": 29.99,
    "merchant": "amazon.de"
  }'

Returns a tx_* row with status: "completed". The matching transaction.completed webhook fires immediately if you have a subscription registered.

Real merchant flows

The simulate endpoint is a stand-in. For real merchant calls, pick the mode that matches the merchant:

MPP

Merchant returns 402 with WWW-Authenticate: Payment. Use POST /v1/mpp/pay to mint a JWE-wrapped credential and settle in one call.

CUA

Merchant only has a checkout form. Mint an autofill token via POST /v1/cua/autofill-tokens, the harness fills the form with a tokenized DPAN.

The six pillars

Tour Pay, Cards, Accounts, Collect, Control, and Intelligence.

Policies

Lock down what your agent can spend, where, and when.

Webhooks

Wire the ~50 event types into your own systems.

MCP tools

The full action-multiplexed reference for all 19 tools.

Getting Started

The Six Pillars

Core Primitives

Payment Modes

Platform

Real merchant flows

MPP

CUA

Next

The six pillars

Policies

Webhooks

MCP tools

​Real merchant flows

MPP

CUA

​Next

The six pillars

Policies

Webhooks

MCP tools

Real merchant flows

Next