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 and starts unverified. See Create a new party.

​

Party Role

The relationship between a party and an account:

• ACCOUNT_HOLDER — the party owns or co-owns the account
• PAYOUT_RECIPIENT — the party is an allowed pay-out destination for the account

A single account can have multiple party roles, enabling joint accounts. A party can hold both roles at once — that’s the self-payout case. See Add a party to an account.

​

KYC / KYB

Know Your Customer (individuals) and Know Your Business (organisations), tracked on two separate fields:

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

You drive verification through the API: mint a hosted verification link, or forward an unused Sumsub share token from a verification you already ran. The verdict arrives asynchronously. Outbound money movement is blocked until the account is VERIFIED. See Individual KYC and Business KYB.

​

Sumsub share token

A single-use, short-lived token from your own Sumsub account that forwards an existing verification to Venly, instead of putting the user through a second flow. Passed as party.sumsubToken when creating an account; individuals on self-custody tenants only. See Sumsub token sharing.

​

IV case reference

ivCaseReference — a durable identifier for a party’s verification case, readable via Get verification linkage. Once set it is never cleared, so quote it to Venly support when investigating a stuck 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. 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.

​

Pay-out

Crypto leaves an account wallet and a bank beneficiary receives fiat — the opposite direction to a pay-in. Requires a payout bank account and a payout route. See Pay-outs.

​

Payout Bank Account

An allow-listed beneficiary bank account, registered against a party. The only place raw bank credentials are accepted; reads expose just accountNumberLast4. See Register a payout bank account.

​

Payout Route

An account-scoped pairing of a payout bank account with a crypto deposit asset. Fixes the beneficiary, rail, asset and fiat currency for every pay-out over it. Only ACTIVE routes are usable. See Create a payout route.

​

Funding Mode (PULL / PUSH)

How a pay-out is funded on-chain:

• PULL — Venly sends from the account wallet using its permit. Created via the API.
• PUSH — the customer sent to the route’s depositAddress themselves; Venly observes the deposit and creates the pay-out. Self-custody only.

​

Deposit Rails

The depositRails array on a virtual bank account, listing every payment rail it is reachable over (ACH, WIRE, RTP, SWIFT, SEPA) with the complete instruction set each one needs. Build payment instructions from this rather than the single-rail summary fields.

​

Ownership Proof

A customer-signed message proving control of a self-custody destination wallet, required for a DIRECT pay-in-mode virtual bank account. Obtained from prepare and signed verbatim.

​

Webhook

A registered HTTPS endpoint Venly pushes asynchronous events to, so you don’t poll. See Webhooks.

---

​

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. Which assets your tenant can settle in is configuration rather than a fixed list — read GET /supported-assets instead of hard-coding one. Support for gasless permits is a property of the token contract on a specific chain, so the same symbol can behave differently across chains.

​

Blockchain Network

The chain an account’s wallet is provisioned on, fixed at account creation. The chains the API accepts are listed in Supported chains & assets; 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 the resource, submit the version it returned, and retry — don’t increment the number yourself.

​

Pagination

Paginated list endpoints accept page (1-based), size, sortOn, and sortOrder, and return a pagination object. Not every list is paginated — check the endpoint. 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