Skip to main content
​
Virtual Bank AccountsErrorsBreaking
Released 1 September 2026 — partner-onboarding error codes renamed
Breaking — two error codes were renamed. On Create a virtual bank account and Prepare a wallet-ownership proof:The HTTP statuses and the retryable/terminal split are unchanged. If your integration matches on the old code strings, update them — the API has returned the new names since this release went live.
The remaining changes in 1.6.0 through 1.8.0 are being documented separately.
​
OnboardingPartiesConsent
Released 23 August 2026 — your end customer accepts partner terms themselves
Our partners require the real end customer to read and accept their terms on a screen themselves; nobody may accept on their behalf. This release surfaces that requirement through the API, and gives you a way to collect the acceptance before any customer data reaches a partner.Partner-terms consent (new)Consent is the final gate after KYC. A verified party whose customer has not accepted cannot get a virtual bank account or receive a pay-out. See Partner-terms consent.
  • Get the consent state — GET /parties/{partyId}/partner-terms. One status and, while outstanding, one consentUrl covering every partner the party is onboarding to. Always current as of the call. Reference
  • Issue a link up front — POST /parties/{partyId}/partner-terms/link. Mints a link so your customer can accept every enabled partner’s latest terms before onboarding begins, rather than hitting the gate later. Reference
  • New enum PartnerTermsStatus (NOT_REQUIRED, REQUIRED, ACCEPTED), and a cached partnerTermsStatus on the party for consumers that would rather poll the plain party read.
ACCEPTED is not terminal. It is evaluated against the terms active now, so enabling a new partner — or a partner publishing a new terms version — moves a party back to REQUIRED. Re-read it rather than recording it as a completed milestone.Each call to the link endpoint also supersedes the previous link for that party — never call it just to check state.
  • Both endpoints fail closed: 503 identity-verification-unavailable is retryable and never means “nothing outstanding”, and a REQUIRED is never returned without a consentUrl.
​
Parties
Released 23 August 2026 — Party email address
  • email on a party — optional, and accepted on create and update. Supply a real address up front for an individual on a self-custody account: when an account holder is onboarded to a partner the email is forwarded with the case, and if the party has none a synthetic address is used instead. Because the partner stores it write-once, adding a real address later does not replace the synthetic one.
​
AssetsWalletsPay-outsTransfers
Released 21 August 2026 — Asset discovery, explicit asset selection, contract-wallet activation, and pay-out ownership proofs
This release makes asset selection explicit. A tenant can now hold the same stablecoin on more than one chain, which means a fiat currency no longer always identifies a single asset — so there are new endpoints to discover what you can use, and new fields to say which one you mean.Discover what you can settle in (new)Stop hard-coding asset lists. See Chains and assets.
  • List supported assets — GET /supported-assets. Every chain/asset pair enabled for your tenant, with decimals and contractAddress. Reference
  • List account supported assets — GET /accounts/{accountId}/supported-assets. The same list annotated with a per-account permitStatus, so you can tell whether this account can move an asset yet. New enum AssetPermitStatus (READY, ACTIVATING, ACTION_REQUIRED, PENDING, FAILED, NO_WALLET). Derived per request and never stored — don’t cache it. Reference
Name the asset a fiat amount settles in
  • chain and asset are now accepted on create fiat transfer. Send them together.
  • Optional while a currency maps to one asset for your tenant; required once it maps to more than one. New codes: ambiguous-asset, chain-and-asset-required-together, asset-currency-mismatch.
If you hold the same stablecoin on two chains, calls that previously worked with currency alone are now rejected with ambiguous-asset rather than settling on an arbitrary chain. Sending chain + asset is always accepted, so the safe move is to always send them.
Activate a smart-contract wallet (new)
  • Verify wallet allowances — POST /accounts/{accountId}/wallets/{walletId}/allowance-verification. A second activation path for self-custody wallets that can’t sign a permit — a Safe, for example. Grant a plain approve() on-chain, then call this; the allowance itself is the consent, so there’s no request body and no proof. Reference
  • WalletStatus gains VERIFYING_ALLOWANCE. It is not a usable state — every check treats it exactly like PENDING. If the verification window closes with assets still uncovered, the wallet reverts to PENDING. See Permits and allowances.
Pay-out route ownership proofs (new)
  • Prepare and submit a route ownership proof — POST /accounts/{accountId}/payout-routes/{routeId}/ownership-proof/prepare and .../complete. Where a destination requires a Travel-Rule proof that you control the source wallet and that wallet is self-custody, registration pauses until its owner signs. Reference
  • PayoutRouteStatus gains AWAITING_OWNERSHIP_PROOF — the only route status that needs an action from you. EIP-191 externally-owned accounts only; ERC-1271 contract signatures are not supported. See Pay-outs.
Pay-out beneficiary contact details
  • beneficiaryEmail and beneficiaryPhoneNumber on register a payout bank account. Some destinations are refused without both. A bank account cannot be edited after registration, so a route built on incomplete beneficiary data fails terminally with beneficiary-data-incomplete and the beneficiary has to be registered again — supply both up front.
​
Pay-outsVerificationWebhooksPay-in
Released 31 July 2026 — Bank pay-outs, identity verification, webhooks, and USD pay-in rails
This release opens up the crypto-to-fiat direction, puts identity verification under your control through the API, and adds webhooks so you no longer have to poll for asynchronous outcomes.Bank pay-outs (new)Send crypto from an account wallet and have a bank beneficiary receive fiat. Three new resources, created once and reused: a payout bank account (whose bank account), a payout route (which bank account pairs with which crypto asset), and a payout (how much, when). See Pay-outs.
  • Register a payout bank account — POST /parties/{partyId}/payout-bank-accounts. The only endpoint that accepts raw rail credentials; the account number is encrypted at rest and only ever returned as accountNumberLast4. Initial rail is US_ACH. Reference
  • List and get payout bank accounts — GET /parties/{partyId}/payout-bank-accounts and .../{payoutBankAccountId}.
  • Create a payout route — POST /accounts/{accountId}/payout-routes. Pairs an allow-listed bank account with a crypto deposit asset; the provider is resolved internally and never exposed. Reference
  • List payout routes — GET /accounts/{accountId}/payout-routes. Exposes depositAddress for an ACTIVE route on a self-custody account. Reference
  • Request a payout — POST /accounts/{accountId}/payouts. Creates a PULL pay-out funded from the account wallet via its permit. Reference
  • List and get payouts — GET /accounts/{accountId}/payouts and .../{payoutId}.
  • New enums: PayoutStatus (REQUESTED, SENDING, PROVIDER_PROCESSING, COMPLETED, REJECTED, FAILED, RETURNED), FundingMode (PULL, PUSH), PayoutRouteStatus, PayoutRail, PayoutBankAccountStatus.
  • PartyRoleType gains PAYOUT_RECIPIENT. A party needs this role, ACTIVE and with cleared KYC/KYB, before a route can be created for its bank account. It may be held alongside ACCOUNT_HOLDER for self-payouts.
A 201 from Request a payout is not a success signal. Permit allowance and wallet balance are deliberately not pre-checked — if either is insufficient, the asynchronous send fails and the pay-out moves to FAILED with a failureReason. Track the outcome via webhook or by reading the pay-out back.
Identity verification (new)Verification is now driven through the API rather than arranged with your Venly contact. See Onboarding & Verification.
  • Create a hosted verification link — POST /parties/{partyId}/verification. Mints a hosted KYC (individual) or KYB (organisation) link. Links do not expire: re-POSTing returns the same URL with 200, or mints a fresh one with 201 if the old was revoked. Reference
  • Get verification linkage — GET /parties/{partyId}/iv-verification. Returns the linkage status and the durable ivCaseReference to quote to support. Reference
  • Forward an existing Sumsub verification — party.sumsubToken on POST /accounts forwards a Sumsub share token instead of re-verifying the user. Individuals on self-custody tenants only. Write-only, never returned. If the forward fails, the entire account-creation transaction rolls back — retry with a fresh token.
  • KycStatus gains NOT_REQUIRED for accounts, letting tenants with tenant-managed KYC declare that they verify end-users themselves. Requires a Venly admin to enable the flag on the company tenant — without it the call fails with kyc-not-required-not-allowed. Granted for testing rather than production use; production integrations verify via a hosted link or Sumsub token sharing.
Webhooks (new)Register HTTPS endpoints and have Venly push asynchronous events instead of polling. See Webhooks.
  • POST /webhooks, GET /webhooks, GET /webhooks/{webhookId}, PUT /webhooks/{webhookId}, DELETE /webhooks/{webhookId}.
  • Ping a webhook — POST /webhooks/{webhookId}/ping queues a synthetic PING event so you can validate your endpoint end-to-end. Reference
  • Authentication is API_KEY (injected into a header you name) or BASIC_AUTHENTICATION. Secrets are write-only and never returned, so an update is a full replacement.
Virtual bank accounts — USD rails and full deposit instructions
  • USD → ACH lane added alongside EUR → SEPA. bankAccountType gains USD_ACH, and the response now carries accountNumber and routingNumber. Requires your tenant to be onboarded for the USD lane with an approved KYB recording.
  • depositRails is a new array carrying the complete instruction set per rail — including the bank and beneficiary postal addresses that wire and SWIFT senders require. USD accounts typically expose ACH, WIRE, RTP and SWIFT; EUR accounts expose a single SEPA rail. Build payment instructions from this rather than the single-rail summary fields.
  • VirtualBankAccountStatus gains PENDING — an EUR account can be returned before the provider has populated its deposit rails. Don’t show payment instructions until it is ACTIVE.
  • Prepare a wallet-ownership proof — POST /accounts/{accountId}/virtual-bank-accounts/prepare. Where a self-custody wallet must prove ownership before a virtual bank account can be created, returns the exact message the customer must sign; submit it back in the new ownershipProof block on create. Reference
New supported chains
  • Ethereum (ETHEREUM) and Solana (SOLANA) are now accepted values. Availability for your company still depends on its configured supportedChains. See Supported chains & assets.
Corrections to previously published docs
  • AmlStatus was documented as PENDING/APPROVED/REJECTED. The actual values are PENDING, APPROVED, FLAGGED, BLOCKED — treat anything other than APPROVED as not-ready. See Account verification.
  • The pay-in session endpoint now documents its manage:pay-in-sessions role and its full error set (no-suitable-provider, company-not-active, account-not-active, idempotency-key-conflict, kyc-required, unsupported-asset, plus 502/503 provider states).
  • vatNumber was listed on the party list item. It is only returned by a single-party fetch, and has been removed from the list schema.
​
ChainsWallets
Released 7 July 2026 — Polygon support and non-custodial accounts
Version 1.1.0 adds Polygon as a supported chain and lets self-custody tenants register an end-customer’s own wallet.New supported chainNon-custodial accounts
  • Self-custody tenants can register an end-customer’s own wallet by passing address when creating an account. See Managed vs. self-custody.
Improvements
  • Retrying an operation with the same idempotency key and body returns the original result. See Idempotency.
  • Account-to-account crypto transfers are now supported for Venly-managed accounts.