Skip to main content
​
Verification
Released 2 October 2026 — follow up a party's KYC and get a completion link
Follow a stalled verification (new)
  • Get a party’s KYC status — GET /parties/{partyId}/kyc-status. Where the party’s KYC/KYB verification stands, read live: a verificationState (AWAITING_CUSTOMER, IN_REVIEW, RESUBMISSION_REQUESTED, APPROVED, DECLINED), the requiredAction the end customer still has to take, and the review outcome per step with reject labels. Reference
  • Issue a KYC completion link — POST /parties/{partyId}/kyc-status/completion-link. Mints a fresh, short-lived link your end customer opens to finish a verification that is waiting on them. 409 kyc-not-completable when it isn’t. Reference
  • POST /accounts returns a completion link up front. When a forwarded sumsubToken still needs the customer to act, the 201 carries an optional verification block with requiredAction, completionUrl and completionUrlExpiresAt. Returned on the create response only. Guide
​
Pay-outsWebhooksPay-insConventionsCompany
Released 1 October 2026 — pay-out route webhooks, tenant selection, request correlation, stricter pay-in session retries
  • Pay-out route webhooks — PAYOUT_ROUTE_ACTIVATED, PAYOUT_ROUTE_AWAITING_OWNERSHIP_PROOF and PAYOUT_ROUTE_REJECTED (with a fixed reason). Keyed per occurrence: deduplicate on payoutRouteId + occurrenceId. You no longer need to poll routes. Guide
  • Get your company profile — GET /company. Your KYB and lifecycle status, wallet type, supported chains and, once billing is set up, a billingUrl to your billing portal. Reference
  • x-tenant-id header. Required when your token grants more than one tenant; omit it otherwise. An invalid selection gets a generic 403. Conventions
  • X-Correlation-Id on every response. Quote it to support. Send your own (or X-Request-Id) to tie our logs to yours. Conventions
  • Contact emails stay with you. A party’s email and a payout bank account’s beneficiaryEmail are no longer sent to payment providers, which get a Venly-controlled address instead. Omitting either never blocks onboarding or registration. beneficiaryPhoneNumber is still forwarded and still needed for USD routes.
  • Paginated lists have a stable default order. Without sortOn, lists now come back by createdAt descending — newest first — where the order was previously unspecified, so a row could appear on two pages or none. sortOrder applies only together with sortOn; on its own it is ignored. Conventions
  • Pay-in session retries must match the original. Reusing an idempotencyKey with a changed body, on another account, or after a failed attempt answers 422 idempotency-conflict; a retry with an identical body still returns the original session. Reference
  • Pay-in session successRedirectUrl and failureRedirectUrl are capped at 2000 characters.
  • Invoice sequenceUrl is clarified as an internal reference you can’t open — use billingUrl on the company profile.
​
Virtual Bank Accounts
Released 11 September 2026 — hotfix
  • Virtual bank accounts accept deposits from any payer. A transfer from a bank account other than the holder’s own was sent back; it is now accepted. No API changes. Guide
​
Pay-insPay-outsWebhooksCredentialsBilling
Released 11 September 2026 — pay-in ledger, self-service credentials, billing, webhook delivery history, SEPA pay-outs
A new account inherits its holder’s verification. Linking a partyId that is already VERIFIED now creates the account VERIFIED instead of VERIFICATION_PENDING, so a customer’s second account needs no second verification. A rejected holder yields a REJECTED account. Code that assumed every new account starts pending should read kycStatus from the create response instead. ReferencePay-in ledger (new)
  • List and get pay-ins — GET /pay-ins, GET /pay-ins/{payInId}. One record per fiat credit that settled (or failed to settle) into an account wallet, with gross and net crypto amounts and the on-chain transaction. The payInId matches the PAY_IN_* webhooks. Guide
  • A pay-in session is now an initiation-only record. It ends at PAYMENT_RECEIVED — PaymentSessionStatus no longer has CONVERTING, MINTING or COMPLETED. Conversion and the crypto credit are tracked on the new pay-in and announced by PAY_IN_SETTLED. Guide
  • Read pay-in sessions back — GET /accounts/{accountId}/fiat-to-crypto/payment-sessions and …/{sessionId}. Sessions could not be read after creation before this release. Reference
  • Close a virtual bank account — POST /accounts/{accountId}/virtual-bank-accounts/{id}/close. Decommissions the bank details at the provider; read providerClosureStatus to know whether they are actually dead. Also how you resolve the new duplicate-eur-vba — one active EUR virtual bank account per account. Guide
  • Creating a hosted pay-in session gained preconditions on accounts that settle through a EUR virtual bank account: retryable 409 vba-not-ready, and 422 vba-required / ambiguous-eur-vba / vba-asset-mismatch / unsupported-currency. A provider refusal now answers 502 rather than 500.
Account self-service (new)
  • API credentials — GET/POST /api-credentials, POST …/{clientId}/secret, PUT …/{clientId}/status. Create, rotate and disable your OAuth credential yourself. The secret is shown exactly once. Requires the dashboard-user scope manage:credentials. Guide
  • Invoices — GET /billing/invoices, …/{invoiceId}, …/{invoiceId}/download (PDF). Cursor-paginated. Scope view:billing. Guide
Webhook delivery history (new)
  • GET /webhooks/{webhookId}/deliveries, …/{deliveryId}, and POST …/{deliveryId}/resend. See what was sent, what your endpoint answered, and replay a FAILURE or DISCARDED delivery with its original payload and notificationId. New enum WebhookDeliveryStatus. Guide
Pay-outs
  • SEPA pay-outs — PayoutRail gains SEPA (requires fiatCurrency: EUR; railDetails takes an iban and optional bic; reads expose ibanLast4). New validation codes invalid-iban, invalid-bic. Guide
  • failureReason on a pay-out is now the documented enum PayoutOutcomeReason — REJECTED_BY_PROVIDER, ROUTE_UNAVAILABLE, SEND_FAILED, RETURNED_BY_BANK, UNKNOWN. Treat it as open. Guide
  • beneficiaryEmail and beneficiaryPhoneNumber on a payout bank account are documented, including that a route fails terminally with beneficiary-data-incomplete when the destination requires them and they are missing.
  • GET /accounts/{accountId}/payouts is additionally sortable on requestedAt.
  • Request partner onboarding — POST /parties/{partyId}/partner-onboarding. Start onboarding a verified individual to our banking partner ahead of provisioning, instead of letting the first virtual-bank-account call trigger it and fail. Guide
​
Maintenance
Released 10 September 2026 — hotfix
  • No public API changes.
​
OnboardingPartiesVirtual Bank AccountsBreaking
Released 1 September 2026 — partner-onboarding status, and its 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.
Partner-onboarding status (new) — GET /parties/{partyId}/partner-onboarding, and partnerOnboardingStatus on the party. The third onboarding gate, next to identity verification and partner-terms consent, is now readable: NOT_STARTED, PENDING, APPROVED or REJECTED. PENDING is exactly the state behind partner-onboarding-pending, so you can wait for APPROVED instead of retrying a failing provisioning call. Guide
​
PartiesOnboarding
Released 25 August 2026 — onboarding without a party email
  • Provisioning a virtual bank account no longer fails with 400 party-email-required when the account holder has no email: a synthetic address is used so onboarding proceeds. Supplying a real address up front is still strongly recommended — see the note on party email.
  • The public spec’s description of the webhook delivery body was corrected to the two-field { eventType, result } shape the webhooks guide has always shown. The wire format did not change.
​
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.