Transactions

A transaction is the source of truth for “money moved”. Every successful charge — MPP, CUA, or simulated — writes a transactions row tied to its agent and intent. Transactions are immutable post-completion; refunds and disputes write new rows that reference the original.

The transaction model

Field	Type	Description
`id`	`tx_*`	Identifier
`intentId`	`int_*`	Authorizing intent (always present in v1.2)
`agentId`	`ag_*`	Owning agent
`cardId`	`ca_*`	Card charged
`amountEuros`	number	EUR amount
`currency`	string	Always `EUR`
`merchant`	string	Merchant name
`merchantMcc`	string	MCC code
`merchantCountry`	string	ISO 3166-1 alpha-2
`rail`	enum	`mpp` · `cua` · `simulate`
`status`	enum	`pending` → `completed` · `failed` · `reversed`
`verified`	boolean	True after `/intents/:id/verify`
`mismatch`	boolean	True if actual deviated beyond `amountTolerancePercent`
`issuerAuthorizationId`	string?	Card-issuer authorization ref
`issuerSettlementId`	string?	Card-issuer settlement ref
`createdAt`	ISO 8601	UTC

Lifecycle

pending → completed     (auth + settlement OK)
pending → failed        (declined or downstream error)
completed → reversed    (refund applied)

For MPP, the rail emits mpp.transaction.completed on success. For CUA and card auths, you’ll see transaction.authorization followed by transaction.settlement, then transaction.completed.

List transactions

curl "https://api.getovra.com/transactions?agentId=ag_...&limit=50" \
  -H "Authorization: Bearer $OVRA_API_KEY"

Cursor-paginated. Supports filters by agent, card, intent, merchant, status, date range.

Refunds

curl -X POST https://api.getovra.com/refunds \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "transactionId": "tx_...",
    "amountEuros": 4.51,
    "reason": "Subscription cancelled"
  }'

The card issuer’s webhook drives the actual reversal — when settled, the original transaction’s status flips to reversed and transaction.refunded fires.

Disputes

See Disputes. One transaction can have at most one open dispute. Disputes carry evidence (receipt, shipping, communication, etc.) and a status FSM.

Memos and comments

# Add a memo (single field, replaces existing)
curl -X PATCH https://api.getovra.com/transactions/tx_.../memo \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -d '{ "memo": "Q2 marketing budget" }'

# Append a comment (audit-logged)
curl -X POST https://api.getovra.com/transactions/tx_.../comments \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -d '{ "comment": "Reviewed by finance" }'

Webhooks

Event	When
`transaction.created`	Row inserted
`transaction.authorization`	Card auth accepted
`transaction.settlement`	Card cleared
`transaction.completed`	Final state — auth + settlement OK
`transaction.declined`	Authorization declined
`transaction.settled`	Settled (legacy alias)
`transaction.updated`	Memo or status changed
`transaction.refunded`	Refund posted
`mpp.transaction.completed`	MPP-rail settle
`verification.mismatch`	Actual diverged from intent beyond tolerance

Plan-tier history retention

Plan	History
Free	30 days
Starter	90 days
Business	365 days
Enterprise	5 years

Older transactions are pruned automatically; export via /audit/export for long-term retention.

Surfaces

Surface	Capability
REST	`/transactions`, `/transactions/:id`, `/refunds`
SDK	`ovra.transactions.`, `ovra.refunds.`
MCP	`ovra_transaction` (read + memo)
Dashboard	`/dashboard/activity` (consolidated view)

Disputes

Challenge a transaction.

Intelligence

Analytics, anomaly detection, audit on top of transactions.

Webhooks

React to transaction events in real time.

Getting Started

The Six Pillars

Core Primitives

Payment Modes

Platform

Transactions

The transaction model

Lifecycle

List transactions

Refunds

Disputes

Memos and comments

Webhooks

Plan-tier history retention

Surfaces

Next

Disputes

Intelligence

Webhooks

​The transaction model

​Lifecycle

​List transactions

​Refunds

​Disputes

​Memos and comments

​Webhooks

​Plan-tier history retention

​Surfaces

​Next

Disputes

Intelligence

Webhooks

The transaction model

Lifecycle

List transactions

Refunds

Disputes

Memos and comments

Webhooks

Plan-tier history retention

Surfaces

Next