Glossary

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

---

​

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 so Venly can move funds). See Wallets & balances.

​

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

​

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.

​

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.

​

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

---

​

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.

​

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

---

​

Status enums (quick reference)

---

​

See also