Skip to main content
Every account starts unverified and must be verified before it can move money. This is the most common reason an otherwise-correct request is rejected, so it’s worth understanding early.

​
The states

An account’s kycStatus (returned by Get an account) is one of:
kycStatusMeaning
VERIFICATION_PENDINGNew account. Can be set up, but can’t move money yet.
VERIFIEDApproved. All operations are available.
REJECTEDVerification was declined.

​
Individuals and organisations (KYC & KYB)

The account’s kycStatus above is what gates money movement. The underlying party is verified too, on a field that depends on its type:
Party typeFieldStates
INDIVIDUALkycStatusVERIFICATION_PENDING → VERIFIED (or REJECTED)
ORGANISATIONkybStatusPENDING → VERIFIED (or DENIED)
KYB (Know Your Business) is the organisation equivalent of KYC — it verifies the company itself (and, typically, its representatives). Read kybStatus from Get a party. Like KYC, it’s reviewed by a Venly admin and runs asynchronously after you create the organisation party.

​
How an account gets verified

Verification is reviewed and approved by a Venly admin — it does not happen through the API, and there’s no endpoint to trigger it. After you create an account, your Venly contact reviews it; once approved, the account’s kycStatus becomes VERIFIED. Check the current status at any time with Get an account and read the kycStatus field.

​
Wallet readiness (AML, and permits for self-custody)

A VERIFIED kycStatus clears the account, but funds move through the account’s wallet, which has its own gate. Each wallet returned by list wallets carries an amlStatus (PENDING → APPROVED). An account is ready to move money when:
CustodyReady when
Venly-managedkycStatus is VERIFIED and the wallet’s amlStatus is APPROVED (both happen during onboarding — no further action).
Self-custodythe above plus a CONFIRMED permit on the account wallet — the one-time signature that lets Venly move its funds.
The wallet has no status field, so use amlStatus (Venly-managed) and permit status (self-custody) as your readiness signals. See Wallets & balances.

​
What’s blocked until VERIFIED

These calls fail while an account is VERIFICATION_PENDING: Each returns an error that means “this account isn’t verified yet” — but the error code and HTTP status depend on the operation, so handle any of them as not-verified rather than matching a single code:
  • Virtual bank account → 400 with code kyc-not-verified:
{
  "success": false,
  "errors": [
    { "code": "kyc-not-verified", "message": "Account KYC status must be VERIFIED to create a virtual bank account. Current status: VERIFICATION_PENDING" }
  ]
}
  • Pay-in session → 422 with code kyc-required:
{
  "success": false,
  "errors": [
    { "code": "kyc-required", "message": "Account {accountId} KYC status is not verified" }
  ]
}
  • Payment request → 400 with code account-not-active:
{
  "success": false,
  "errors": [
    { "code": "account-not-active", "message": "Account KYC status must be VERIFIED to authorize payments. Current status: VERIFICATION_PENDING" }
  ]
}
Transfers are gated the same way; check the transfer endpoints for the exact status code.

​
What you can do before verification

Plenty of setup doesn’t require a verified account:
  • Create parties and accounts
  • Add and remove party roles
  • Read wallets, balances, permits, and allowances
  • For self-custody, sign and submit the token permit — see Approving transfers without gas
Build the pending state into your flow: create the account, then wait for your Venly contact to verify it (poll Get an account until kycStatus is VERIFIED) before attempting transfers, payments, pay-ins, or virtual bank accounts.

​
Next steps

Approve transfers (self-custody)

Activate a self-custody wallet so Venly can move its funds.

Integration walkthrough

See verification within the full end-to-end flow.