Collect

Collect closes the loop on agent-native economies — your agent doesn’t only spend, it can also earn. Issue a payment request and the counterparty pays from another Ovra wallet (instant, free) or via SEPA with reference matching (external).

Internal Ovra-to-Ovra works today. External SEPA inbound matching is on the roadmap and is currently rejected by the /settle endpoint. See the status table below.

Why this matters

If your agent does work that someone else paid for — services, goods, microtransactions, API calls — you need a way to collect. Without Collect, “agent payments” is a one-way street. With it, agents can run businesses.

The payment-request model

Field	Description
`id`	`pr_*`
`destinationWalletId`	Where settled funds land
`amountEuros`	EUR amount, ≤ 1,000,000
`description`	Free text; surfaces in the payer view
`counterpartyOwnerId`	Set for internal requests (other Ovra customer)
`sepaInstructions`	`{ iban, bic, reference }` for external requests; reference is `OVRA-PR-<hex>`
`payerName` / `payerEmail`	Optional — surfaces on the payer page
`agentId`	Optional — bind the request to a specific agent
`expiresAt`	Optional TTL (max 30 days)
`status`	`pending → paid · expired · cancelled`

Operations

Endpoint	Purpose
`POST /claim/requests`	Create a request. Pass `counterpartyOwnerId` for internal, omit for external.
`GET /claim/requests`	List your requests. Filter `status`, use `inbound=true` for the payer view.
`GET /claim/requests/:id`	Detail — owner or counterparty allowed.
`POST /claim/requests/:id/settle`	Internal only. Atomic wallet→wallet debit/credit + ledger + transfer row.
`POST /claim/requests/:id/cancel`	Cancel an unpaid request.
`GET /claim/requests/:id/pay`	Public payer page — no auth required.

The pillar is named Collect but the routes still mount under /claim/*. The route rename is upcoming tech-debt; the URL contract is stable.

Create a request

curl -X POST https://api.getovra.com/claim/requests \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "destinationWalletId": "wal_...",
    "amountEuros": 49.00,
    "description": "Research report — 3 sources",
    "payerEmail": "ops@acme.example"
  }'

const req = await ovra.collect.create({
  destinationWalletId: "wal_...",
  amountEuros: 49,
  description: "Research report — 3 sources",
  payerEmail: "ops@acme.example",
});

Response:

{
  "id": "pr_...",
  "amountEuros": 49,
  "status": "pending",
  "settlementType": "external",
  "sepaInstructions": {
    "iban": "DE89370400440000001234",
    "bic": "PLINDE21",
    "reference": "OVRA-PR-a3f9b1c2"
  },
  "expiresAt": "2026-05-20T10:00:00Z"
}

Settle path matrix

Internal (Ovra → Ovra)
External (SEPA inbound)

Counterparty has an Ovra wallet. Pass counterpartyOwnerId in the create call. The counterparty calls POST /claim/requests/:id/settle with sourceWalletId. We run the debit and credit in a single transaction:

SQL BEGIN
UPDATE wallets SET balance_euros = balance_euros - amount WHERE id = :src AND balance_euros >= amount
UPDATE wallets SET balance_euros = balance_euros + amount WHERE id = :dst
INSERT ledger_entries (debit + credit), transfers row, mark request paid
COMMIT
Fire claim.request.paid webhook

Result: instant, free, fully auditable. ✅ Production-ready.

Counterparty is outside Ovra. The request returns sepaInstructions with a OVRA-PR-<hex> reference. The payer initiates SEPA with that reference.⚠️ Currently TODO. /settle rejects external requests today (no SEPA-In reconciliation pipeline yet). Choices on the table:

Integrate a dedicated SEPA-In provider for reference matching.
Use the banking partner’s SEPA-Inbound feed (v1.3+ live mode).
Manual operator match in dashboard for the demo phase.

Surfaces

Surface	Status
REST API	Full
SDK (`@ovra/sdk`)	`ovra.collect.*`
MCP	`ovra_claim` (action-multiplexed) — tool name will rename to `ovra_collect` in a future MCP release
Dashboard	`/dashboard/collect` — create drawer, filter list, detail drawer

Webhooks

Subscribe to these events to react in real time:

claim.request.created
claim.request.paid
claim.request.expired
claim.request.cancelled

See Webhooks for delivery, retries, and signature verification.

Accounts

Wallets, IBANs, transfers — where the funds live.

Webhooks

Fire-and-forget delivery for claim.request.* events.

Getting Started

The Six Pillars

Core Primitives

Payment Modes

Platform

Why this matters

The payment-request model

Operations

Create a request

Settle path matrix

Surfaces

Webhooks

Next

Accounts

Webhooks

​Why this matters

​The payment-request model

​Operations

​Create a request

​Settle path matrix

​Surfaces

​Webhooks

​Next

Accounts

Webhooks

Why this matters

The payment-request model

Operations

Create a request

Settle path matrix

Surfaces

Webhooks

Next