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.

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

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