Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getovra.com/llms.txt

Use this file to discover all available pages before exploring further.

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

FieldTypeDescription
idtx_*Identifier
intentIdint_*Authorizing intent (always present in v1.2)
agentIdag_*Owning agent
cardIdca_*Card charged
amountEurosnumberEUR amount
currencystringAlways EUR
merchantstringMerchant name
merchantMccstringMCC code
merchantCountrystringISO 3166-1 alpha-2
railenummpp · cua · simulate
statusenumpending → completed · failed · reversed
verifiedbooleanTrue after /intents/:id/verify
mismatchbooleanTrue if actual deviated beyond amountTolerancePercent
issuerAuthorizationIdstring?Card-issuer authorization ref
issuerSettlementIdstring?Card-issuer settlement ref
createdAtISO 8601UTC

​
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

EventWhen
transaction.createdRow inserted
transaction.authorizationCard auth accepted
transaction.settlementCard cleared
transaction.completedFinal state — auth + settlement OK
transaction.declinedAuthorization declined
transaction.settledSettled (legacy alias)
transaction.updatedMemo or status changed
transaction.refundedRefund posted
mpp.transaction.completedMPP-rail settle
verification.mismatchActual diverged from intent beyond tolerance

​
Plan-tier history retention

PlanHistory
Free30 days
Starter90 days
Business365 days
Enterprise5 years
Older transactions are pruned automatically; export via /audit/export for long-term retention.

​
Surfaces

SurfaceCapability
REST/transactions, /transactions/:id, /refunds
SDKovra.transactions.*, ovra.refunds.*
MCPovra_transaction (read + memo)
Dashboard/dashboard/activity (consolidated view)

​
Next

Disputes

Challenge a transaction.

Intelligence

Analytics, anomaly detection, audit on top of transactions.

Webhooks

React to transaction events in real time.