> ## 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.

# Accounts

> EUR wallets with dedicated IBANs, hierarchical structure, and a full ledger.

Accounts is the money-holding pillar. Wallets hold EUR balances, transfers move them between Ovra wallets or out to external IBANs via SEPA, and beneficiaries are saved external recipients. Multi-wallet per organization is supported, and wallets can be hierarchical (parent → child) for cost-center splits.

<Note>
  Sandbox-only today. SEPA-out is simulated end-to-end with deterministic IBANs (`DE89370400440{N}`). v1.3+ wires real SEPA settlement through the banking partner.
</Note>

## The wallet model

| Field              | Description                                                  |
| ------------------ | ------------------------------------------------------------ |
| `id`               | `wal_*`                                                      |
| `name` / `purpose` | Free text                                                    |
| `currency`         | Always `EUR`                                                 |
| `balanceEuros`     | Numeric, EUR                                                 |
| `iban` / `bic`     | Dedicated IBAN per wallet (sandbox: deterministic per index) |
| `parentWalletId`   | Optional — supports hierarchical wallets                     |
| `isDefault`        | Exactly one wallet per org is the default                    |
| `status`           | `active` · `frozen` · `closed`                               |
| `metadata`         | Arbitrary JSON                                               |

## Operations

| Endpoint                           | Purpose                           |
| ---------------------------------- | --------------------------------- |
| `GET /wallets`, `GET /wallets/:id` | List + detail                     |
| `POST /wallets`                    | Create (multiple per org allowed) |
| `PATCH /wallets/:id`               | Update name / purpose / default   |
| `DELETE /wallets/:id`              | Close (terminal)                  |

The same surface is mirrored under `/accounts/*` for clients that prefer the business term.

## Create a wallet

<CodeGroup>
  ```bash curl theme={}
  curl -X POST https://api.getovra.com/wallets \
    -H "Authorization: Bearer $OVRA_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $(uuidgen)" \
    -d '{
      "name": "Marketing budget",
      "purpose": "Q2 ad spend",
      "currency": "EUR"
    }'
  ```

  ```ts SDK theme={}
  const wallet = await ovra.wallets.create({
    name: "Marketing budget",
    purpose: "Q2 ad spend",
  });
  ```
</CodeGroup>

## Beneficiaries — saved external recipients

| Field                                     | Description              |
| ----------------------------------------- | ------------------------ |
| `id`                                      | `ben_*`                  |
| `name`, `iban`, `bic`, `country`, `email` | Recipient detail         |
| `ibanMasked`                              | Display-safe masked form |
| `status`                                  | `active` etc.            |

```bash theme={}
curl -X POST https://api.getovra.com/beneficiaries \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme GmbH",
    "iban": "DE89370400440000001234",
    "country": "DE"
  }'
```

IBANs are validated by format check (full mod-97 happens server-side at the banking partner). Bank URLs are SSRF-checked.

## Transfers

| Field                                              | Description                                     |
| -------------------------------------------------- | ----------------------------------------------- |
| `sourceWalletId`                                   | Origin                                          |
| `destinationType`                                  | `wallet` or `beneficiary` (discriminated union) |
| `destinationWalletId` / `destinationBeneficiaryId` | Target                                          |
| `amountEuros`                                      | EUR                                             |
| `transferMethod`                                   | `SEPA` or `SEPAINST` (SEPA Instant)             |
| `purpose`                                          | Free text                                       |
| `groupId`                                          | For split transfers                             |

```bash theme={}
curl -X POST https://api.getovra.com/transfers \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "sourceWalletId": "wal_...",
    "destinationType": "beneficiary",
    "destinationBeneficiaryId": "ben_...",
    "amountEuros": 199.00,
    "transferMethod": "SEPAINST",
    "purpose": "Invoice 2026-042"
  }'
```

### Split transfers

Atomic 1-to-N split with mixed percentage and fixed-amount legs (sum of percentages ≤ 100):

```bash theme={}
curl -X POST https://api.getovra.com/transfers/split \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "sourceWalletId": "wal_...",
    "totalAmountEuros": 1000,
    "purpose": "Q2 royalties",
    "legs": [
      { "destinationType": "wallet", "destinationWalletId": "wal_a", "percentage": 60 },
      { "destinationType": "wallet", "destinationWalletId": "wal_b", "percentage": 30 },
      { "destinationType": "beneficiary", "destinationBeneficiaryId": "ben_x", "percentage": 10 }
    ]
  }'
```

## Funding

`POST /fund` tops up a wallet. In sandbox, use `simulate: true` for instant balance:

```bash theme={}
curl -X POST https://api.getovra.com/fund \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "walletId": "wal_...", "amountEuros": 500, "simulate": true }'
```

v1.3+ adds real SEPA inbound via the dedicated wallet IBAN.

## Ledger

Every money movement appends one or more rows to `ledger_entries`:

| Field           | Description                                |
| --------------- | ------------------------------------------ |
| `accountType`   | `wallet` · `card` · `overdraft`            |
| `accountId`     | Wallet, card, or owner                     |
| `amountEuros`   | Signed (debit negative, credit positive)   |
| `type`          | `payment`, `transfer`, `mpp_payment`, etc. |
| `reference`     | Cross-link to transaction or transfer      |
| `correlationId` | Workflow correlation                       |

Append-only — never updated, never deleted.

## Plan-tier volume

| Plan       | Volume €/mo |
| ---------- | ----------- |
| Free       | 150         |
| Starter    | 2,000       |
| Business   | 5,000       |
| Enterprise | Unlimited   |

Overage is a soft cap with a 0.3–0.5% fee on volume above the limit. No hard block.

## Webhooks

* `wallet.created`
* `wallet.funded`
* `wallet.credited`
* `transfer.completed`
* `transfer.failed`
* `transfer.split.completed`

## Surfaces

| Surface   | Capability                                                                   |
| --------- | ---------------------------------------------------------------------------- |
| REST      | `/wallets`, `/accounts`, `/transfers`, `/beneficiaries`, `/fund`             |
| SDK       | `ovra.wallets`, `ovra.transfers`, `ovra.beneficiaries`                       |
| MCP       | `ovra_account`, `ovra_payment`, `ovra_vendor`                                |
| Dashboard | `/dashboard/accounts` (wallets, transfers, beneficiaries in one tabbed view) |

## Next

<CardGroup cols={2}>
  <Card title="Collect" icon="hand-holding-dollar" href="/concepts/collect">
    Inbound payment requests against your wallets.
  </Card>

  <Card title="Funding" icon="piggy-bank" href="/concepts/funding">
    How EUR enters Ovra in sandbox vs live.
  </Card>

  <Card title="Compliance" icon="scale-balanced" href="/concepts/compliance">
    Where the funds live — partner posture.
  </Card>
</CardGroup>