Glossary

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.

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.

​

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.

​

KYC / KYB

Know Your Customer (individuals) and Know Your Business (organisations). Identity verification that runs after party creation. The party’s kycStatus transitions through PENDING → IN_PROGRESS → VERIFIED (or REJECTED / MANUAL_REVIEW). Outbound transfers are blocked until VERIFIED.

---

​

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, BLOCKED.

​

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.

​

Custodial Wallet

A blockchain wallet managed by Venly on behalf of an account. Venly holds the keys; balances move via API calls rather than on-chain signatures. Each wallet is bound to one chain (BASE or AVALANCHE in Release 1).

​

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.

​

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

Generic term for any value movement out of an account. Three subtypes:

• Fiat transfer — outbound SEPA payout to a bank account
• Crypto transfer — outbound on-chain transfer to a blockchain address
• Account-to-Account transfer — internal, between two Venly-custodied accounts (no on-chain fee, settles in seconds)

​

Transfer Status

Lifecycle states: PENDING → PROCESSING → COMPLETED (or FAILED with failureCode and failureReason).

​

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.

​

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.

​

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.

​

Stablecoin

A cryptocurrency pegged to a fiat currency. Supported in Release 1: USDC, EURC, USDT.

​

Blockchain Network

The chain the account’s wallet is provisioned on. Supported in Release 1: BASE, AVALANCHE.

---

​

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

---

​

Status enums (quick reference)

---

​

See also