> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venlyfinance.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Glossary

> Definitions for parties, accounts, party roles, virtual bank accounts, custodial wallets, transfers, permits, and other Finance API concepts.

Terms used throughout the Finance API reference and guides. Each definition links to the primary endpoint or guide where the concept is used.

## Identity

### Party

The legal identity behind every account. Two types:

* **`INDIVIDUAL`** — a natural person (requires `firstName`, `lastName`)
* **`ORGANISATION`** — a company or business (requires `name`, optionally `vatNumber`)

A party is created independently of accounts; KYC/KYB runs asynchronously after creation. See [Create a new party](/api-reference/Finance-API/parties/create-a-new-party).

### Party Role

The relationship between a party and an account. Currently only one role type exists:

* **`ACCOUNT_HOLDER`** — the party owns or co-owns the account

A single account can have multiple party roles, enabling joint accounts. See [Add a party to an account](/api-reference/Finance-API/accounts/add-a-party-to-an-account).

### KYC / KYB

**Know Your Customer** (individuals) and **Know Your Business** (organisations). Identity verification that runs after party creation, tracked on two separate fields:

* **`kycStatus`** (individuals & accounts) — `VERIFICATION_PENDING → VERIFIED` (or `REJECTED`)
* **`kybStatus`** (organisations) — `PENDING → VERIFIED` (or `DENIED`)

Outbound money movement is blocked until the account is `VERIFIED`. See [Account verification](/guides/finance/kyc-verification).

***

## Account structure

### Account

The container that holds wallets, virtual bank accounts, and transfer history for a party (or set of parties). Pinned to a single blockchain network at creation. Statuses: `ACTIVE`, `SUSPENDED`, `CLOSED`.

### External ID

A merchant-supplied unique identifier for an account or party (`externalId` field). Use it as a shortcut in transfer requests (`receiverExternalId`) instead of looking up the Venly UUID.

### Account wallet

The wallet that holds an account's balance, bound to one chain. Its `type` is either **`VENLY_MANAGED`** (Venly holds the keys; funds move via API calls) or **`SELF_CUSTODY`** (your customer holds the keys and signs a one-time [permit](/guides/finance/permits-and-allowances) so Venly can move funds). See [Wallets & balances](/guides/finance/wallets).

### Escrow wallet

A second, always Venly-managed wallet on the account that holds funds in flight during settlement — for example, amounts reserved by a [payment request](/guides/finance/payment-requests). You never sign for it.

### Orchestration wallet

The Venly-controlled wallet that pulls funds from a self-custody account wallet via ERC-20 `transferFrom`. It is the **spender** a self-custody permit authorises, and it's returned as `orchestrationWallet` on the [allowances](/api-reference/Finance-API/allowances/get-wallet-token-allowances) response.

### Virtual Bank Account (VBA)

A bank account reference (IBAN + BIC for EUR\_SEPA) attached to a Venly account. Used to receive fiat funding that's auto-converted to crypto and credited to the wallet. See [Create a virtual bank account](/api-reference/Finance-API/virtual-bank-accounts/create-a-virtual-bank-account).

### IBAN / BIC

**International Bank Account Number** and **Bank Identifier Code** — the standard EUR\_SEPA addressing format returned on a virtual bank account.

### Reference Code

A unique string returned with each VBA. The end user must include this in their SEPA payment message — it's how the incoming wire is matched to the right account. Without it, settlement falls back to manual reconciliation.

### Beneficiary Name

The legal name on the bank account record (typically a Venly custody entity). Display this to end users alongside the IBAN when they initiate a wire.

***

## Money movement

### Transfer

A value movement from one account to another, addressed by `receiverAccountId` or `receiverExternalId`. Two flavors, depending on how you denominate the amount:

* **Fiat transfer** — you send a fiat `currency` + `amount`; it's resolved to the underlying stablecoin and settled on-chain. The response carries a `fiatOrigin` block (original currency, amount, exchange rate).
* **Crypto transfer** — you send a crypto `asset` + `chain` + `amount`, moved directly between the accounts on-chain.

See [Transfers](/guides/finance/transfers).

### Transfer Status

Lifecycle states: `PENDING → COMPLETED` (or `FAILED` with an `errorMessage`).

### Payment Session (Fiat-to-Crypto)

A hosted checkout flow that converts a card or bank payment into crypto credited to an account's wallet. Returns a `paymentUrl` you redirect the user to. See [Create a fiat-to-crypto payment session](/api-reference/Finance-API/fiat-to-crypto-payment-sessions/create-a-fiat-to-crypto-payment-session).

### Payment Request

A pre-authorised request for funds, used in card-provider integrations. Two endpoints exist: `/payment-requests` (for card providers) and `/accounts/{id}/payment-requests` (account-scoped).

***

## On-chain primitives

### Permit (EIP-2612)

A signed message that grants a spender permission to move tokens from a wallet, without an on-chain approval transaction. Used to delegate spending authority cheaply. See [Get permit messages](/api-reference/Finance-API/permits/get-permit-messages).

### Allowance (ERC-20)

The amount of a token that a third party is approved to spend from a wallet. Queried per wallet + token. See [Get wallet token allowances](/api-reference/Finance-API/allowances/get-wallet-token-allowances).

### Stablecoin

A cryptocurrency pegged to a fiat currency. Supported assets: `USDC`, `EURC`, `USDT`, `USDS`.

### Blockchain Network

The chain an account's wallet is provisioned on, fixed at account creation. The API supports `BASE`, `AVALANCHE`, and `POLYGON`; the chains available to **your** company are configured by Venly. Requesting a chain your company isn't set up for returns `400 invalid-request` with a message listing your supported chains. See [Supported chains & assets](/guides/finance/supported-chains-and-assets).

***

## API mechanics

### Idempotency Key

A UUID supplied in the request body of state-changing endpoints to make retries safe. Same key + same body returns the original response; same key + different body returns `422`. See the [Idempotency](/getting-started/conventions#idempotency) rules.

### Optimistic Locking (`version`)

On update endpoints, the request body includes a `version` integer matching the resource's current version. Concurrent updates with a stale `version` return `409 Conflict`. Refetch, increment, retry.

### Pagination

List endpoints accept `page` (1-based), `size`, `sortOn`, and `sortOrder` query parameters and return a `pagination` object in the response. See [Pagination conventions](/getting-started/conventions#pagination).

### Error handling

Every response carries a `success` flag and, on failure, an `errors` array of `{ code, message }`. Branch on the stable `code`. See the [Errors & error codes](/guides/finance/errors) reference.

***

## Status enums (quick reference)

| Resource                                   | Statuses                                                                                                                                          |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Party (`status`)                           | `ACTIVE`, `SUSPENDED`, `BLOCKED`                                                                                                                  |
| Party Role                                 | `ACTIVE`, `INACTIVE`                                                                                                                              |
| KYC (`kycStatus` — individuals & accounts) | `VERIFICATION_PENDING`, `VERIFIED`, `REJECTED`                                                                                                    |
| KYB (`kybStatus` — organisations)          | `PENDING`, `VERIFIED`, `DENIED`                                                                                                                   |
| Account (`status`)                         | `ACTIVE`, `SUSPENDED`, `CLOSED`                                                                                                                   |
| Wallet AML (`amlStatus`)                   | `PENDING`, `APPROVED`, `REJECTED`                                                                                                                 |
| Virtual Bank Account                       | `ACTIVE`, `CLOSED`                                                                                                                                |
| Transfer                                   | `PENDING`, `COMPLETED`, `FAILED`                                                                                                                  |
| Payment Request                            | `PENDING`, `RESERVED`, `SETTLING`, `SETTLED`, `SETTLED_WITH_SHORTFALL`, `REVERSING`, `REVERSED`, `FAILED`                                         |
| Payment Execution                          | `PENDING`, `RESERVED`, `SETTLED`, `REVERSED`, `FAILED`                                                                                            |
| Permit                                     | `PENDING`, `SUBMITTED`, `CONFIRMED`, `FAILED`                                                                                                     |
| Payment Session                            | `CREATED`, `PENDING_PAYMENT`, `PAYMENT_RECEIVED`, `CONVERTING`, `MINTING`, `COMPLETED`, `FAILED`, `EXPIRED`, `CANCELLED`, `REFUNDING`, `REFUNDED` |

<Note>
  A wallet has **no `status` field** — `GET .../wallets` returns `amlStatus` only. Readiness isn't a single returned value: a **Venly-managed** wallet is ready once `amlStatus` is `APPROVED`; a **self-custody** wallet is ready once its [permit](/guides/finance/permits-and-allowances) `status` is `CONFIRMED`.
</Note>

***

## See also

<CardGroup cols={2}>
  <Card title="Integration walkthrough" icon="route" href="/guides/finance/integration-walkthrough">
    Watch every term above used in context, end to end.
  </Card>

  <Card title="API conventions" icon="list-check" href="/getting-started/conventions">
    Idempotency, pagination, and versioning rules.
  </Card>
</CardGroup>