Integration Walkthrough - Venly Finance

This guide walks the Finance API end-to-end — from creating your first party to settling a transfer. Every step uses real request and response shapes. Run it against staging and you’ll have a working integration.

Base URL (staging): https://api-staging.venlyfinance.com/v1 Auth: OAuth2 Bearer token in the Authorization header. Tokens expire after 5 minutes — see the Authentication guide.

What you’ll build

Onboard a party (your customer) — created ACTIVE immediately
Open an account for them (its custodial wallet is provisioned automatically)
Get the party verified through the API
Have the customer accept the partner terms on a hosted page
Issue a EUR IBAN so they can fund via SEPA
Send an outbound transfer

The big gate to design around: an account is created unverified (kycStatus: VERIFICATION_PENDING) and its party must complete verification before it can move money. A party’s status is ACTIVE right away, which is not the same as being verified. See Account verification.

Prerequisites

Staging credentials

A client_id and client_secret from your Venly contact. Staging calls don’t move real money.

An HTTP client

All examples use curl. Postman, HTTPie, or any SDK works equally well.

A UUID generator

Money-moving endpoints require an idempotencyKey (UUID v4) — uuidgen, [guid]::NewGuid(), or crypto.randomUUID().

Step 1 — Authenticate

Exchange your client credentials for a Bearer token. Every subsequent call needs it in the Authorization header.

curl -X POST https://login-staging.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response

{ "access_token": "eyJhbGciOi...", "expires_in": 300, "token_type": "Bearer" }

Cache the token. Refresh on 401 Unauthorized or a few seconds before expires_in elapses — don’t request a new token on every call.

Step 2 — Create a party

A party is the person or organisation behind an account — INDIVIDUAL (natural person) or ORGANISATION (company). It’s created ACTIVE immediately — creating a party does not verify it, and status: ACTIVE is not a verification result. Verification happens later, in Step 4.

curl -X POST https://api-staging.venlyfinance.com/v1/parties \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "partyType": "INDIVIDUAL",
    "externalId": "user-12345",
    "firstName": "Jane",
    "lastName": "Doe",
    "address": { "addressLine1": "1 Example Street", "city": "Amsterdam", "postalCode": "1011AB", "country": "NL" }
  }'

Response (201)

{
  "success": true,
  "result": {
    "id": "7e3b9c2a-1f4d-4a8b-9c11-2d6e8f0a1b22",
    "externalId": "user-12345",
    "partyType": "INDIVIDUAL",
    "status": "ACTIVE",
    "firstName": "Jane",
    "lastName": "Doe",
    "createdAt": "2026-01-15T09:30:00Z",
    "updatedAt": "2026-01-15T09:30:00Z",
    "version": 0
  }
}

For an organisation, swap the body:

{ "partyType": "ORGANISATION", "externalId": "org-67890", "name": "Acme B.V.", "vatNumber": "NL123456789B01" }

Step 3 — Open an account

An account holds the wallet, IBANs, and transfer history. Link the party from Step 2 with partyId (it becomes the ACCOUNT_HOLDER). The custodial wallet is provisioned automatically — there’s no separate “create wallet” call. The only difference between company types is the wallet address:

Venly-managed — Venly creates and holds the wallet. Omit address.
Self-custody — the customer controls the wallet. Send their address (required).

curl -X POST https://api-staging.venlyfinance.com/v1/accounts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "acct-12345",
    "name": "Jane Doe — Main",
    "chain": "BASE",
    "partyId": "7e3b9c2a-1f4d-4a8b-9c11-2d6e8f0a1b22"
  }'

curl -X POST https://api-staging.venlyfinance.com/v1/accounts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "acct-12345",
    "name": "Jane Doe — Main",
    "chain": "BASE",
    "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    "partyId": "7e3b9c2a-1f4d-4a8b-9c11-2d6e8f0a1b22"
  }'

Response (201)

{
  "success": true,
  "result": {
    "id": "b2a1f0e9-8c7d-4e3a-9f21-0a1b2c3d4e5f",
    "externalId": "acct-12345",
    "name": "Jane Doe — Main",
    "kycStatus": "VERIFICATION_PENDING",
    "status": "ACTIVE",
    "createdAt": "2026-01-15T09:30:00Z",
    "version": 0
  }
}

Set a meaningful externalId — your own user/customer ID. It doubles as a receiver shortcut in transfers (receiverExternalId), so you don’t have to look up the Venly UUID every time.

Add a second account holder (optional)

curl -X POST https://api-staging.venlyfinance.com/v1/accounts/{accountId}/party-roles \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "partyId": "ANOTHER_PARTY_UUID", "roleType": "ACCOUNT_HOLDER" }'

Step 4 — Get the account verified

The account is created with kycStatus: VERIFICATION_PENDING. Mint a hosted link with POST /parties/{partyId}/verification and hand it to the end-user, or forward an existing Sumsub verification at account creation. The verdict arrives asynchronously and kycStatus becomes VERIFIED. See Onboarding & Verification. Poll the account until it flips:

curl https://api-staging.venlyfinance.com/v1/accounts/{accountId} \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response (200)

{ "success": true, "result": { "id": "b2a1f0e9-...", "kycStatus": "VERIFIED", "status": "ACTIVE", "version": 1 } }

Until then, creating IBANs, transfers, and pay-in sessions all fail with a KYC error — the exact code and HTTP status vary by operation (e.g. 400 kyc-not-verified for IBANs, 422 kyc-required for pay-in sessions). See Account verification for the full list of what’s gated.

Step 5 — Have the customer accept the partner terms

Verification proves who your customer is. It does not cover the terms our partners require them to accept — and they must accept those themselves, on a page we hand you a link to. Until they do, issuing an IBAN in the next step is blocked. Read the party’s consent state:

curl https://api-staging.venlyfinance.com/v1/parties/{partyId}/partner-terms \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response (200)

{
  "success": true,
  "result": {
    "partyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "REQUIRED",
    "consentUrl": "https://onboard.venly.io/partner-terms?token=cons-tok-9f3a2b"
  }
}

REQUIRED means hand consentUrl to your customer. You cannot complete this for them. Once they accept, the status becomes ACCEPTED and onboarding continues.

You can get ahead of this instead of waiting for it to block you: POST /parties/{partyId}/partner-terms/link mints a link immediately, so the customer accepts every partner’s terms before any of their data is sent to a partner. Collecting consent during your own onboarding is usually the better experience.

ACCEPTED is not permanent. Adding a partner, or a partner publishing a new terms version, moves the party back to REQUIRED. Re-read it rather than recording it once. See Partner-terms consent.

Step 6 — View the wallet

The wallet was created with the account. Read it (and its balances) any time:

curl https://api-staging.venlyfinance.com/v1/accounts/{accountId}/wallets \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response (200)

{
  "success": true,
  "result": [
    {
      "id": "9f8e7d6c-5b4a-4938-8271-6a5b4c3d2e1f",
      "chain": "BASE",
      "type": "SELF_CUSTODY",
      "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
      "balances": [
        { "asset": "USDC", "contractAddress": "0x036CbD53842c5426634e7929541eC2318f3dCF7e", "amount": { "total": "0", "available": "0", "reserved": "0" } }
      ],
      "amlStatus": "PENDING"
    }
  ]
}

Balance amounts are decimal strings. type is VENLY_MANAGED or SELF_CUSTODY depending on your company (this example shows self-custody). A wallet has no status field — readiness shows as amlStatus: APPROVED (Venly-managed) or a CONFIRMED permit (self-custody).

Venly-managed: nothing to do here — the wallet is ready once its amlStatus is APPROVED (handled during onboarding).Self-custody: before this wallet can send funds, the customer signs a one-time permit so Venly can move their tokens (do this once after the account is set up). The wallet is ready once that permit is CONFIRMED.

Step 7 — Issue a virtual bank account (IBAN)

Once the account is VERIFIED and its partner-terms consent is ACCEPTED, attach an IBAN so it can be funded via SEPA. Incoming euros are auto-converted to the targetCryptocurrency and credited to the wallet — read GET /supported-assets for the assets your tenant can settle in.

curl -X POST https://api-staging.venlyfinance.com/v1/accounts/{accountId}/virtual-bank-accounts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe — EUR Funding",
    "inCurrency": "EUR",
    "targetCryptocurrency": "USDC",
    "idempotencyKey": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }'

Response (201)

{
  "success": true,
  "result": {
    "id": "4d5e6f70-8192-4a3b-9c4d-5e6f7081920a",
    "accountId": "b2a1f0e9-8c7d-4e3a-9f21-0a1b2c3d4e5f",
    "bankAccountType": "EUR_SEPA",
    "status": "ACTIVE",
    "currency": "EUR",
    "targetCryptocurrency": "USDC",
    "iban": "DE89370400440532013000",
    "bic": "DEUTDEDB",
    "referenceCode": "VFY-7K2Q-931"
  }
}

Surface the referenceCode to your end user when they initiate a SEPA transfer — it’s what links the incoming wire to this account. Without it, settlement falls back to manual reconciliation.

Step 8 — Fund the account

Option A — SEPA transfer to the IBAN

The customer sends EUR from their bank to the IBAN from Step 7, including the referenceCode in the payment reference. On receipt, Venly converts EUR → the target crypto and credits the wallet.

Option B — Hosted fiat-to-crypto pay-in

Create a pay-in session and redirect the customer to the returned paymentUrl.

curl -X POST https://api-staging.venlyfinance.com/v1/accounts/{accountId}/fiat-to-crypto/payment-sessions \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inAmount": "100.00",
    "inCurrency": "EUR",
    "outCryptocurrency": "USDC",
    "callbackUrl": "https://your-app.com/webhooks/pay-in",
    "successRedirectUrl": "https://your-app.com/onboarding/funded",
    "failureRedirectUrl": "https://your-app.com/onboarding/retry",
    "idempotencyKey": "c7e8d9f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f"
  }'

The response carries a paymentUrl. When the customer completes payment, the wallet is credited and your callbackUrl is invoked.

Step 9 — Send a transfer

Transfers move funds between two Venly accounts — identify the receiver by receiverAccountId or by your own receiverExternalId. Both the sender and the receiver accounts must be VERIFIED; sending to an unverified receiver fails with 422 receiver-kyc-not-verified.

Crypto transfer

curl -X POST https://api-staging.venlyfinance.com/v1/accounts/{senderAccountId}/transfers/crypto \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "receiverExternalId": "acct-67890",
    "chain": "BASE",
    "asset": "USDC",
    "amount": 25,
    "description": "Invoice #1138 settlement",
    "idempotencyKey": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

Response (201)

{
  "success": true,
  "result": {
    "id": "a1b2c3d4-e5f6-4789-9abc-def012345678",
    "senderAccountId": "b2a1f0e9-8c7d-4e3a-9f21-0a1b2c3d4e5f",
    "receiverAccountId": "c3b2a1f0-9d8c-4e3a-bf21-1a2b3c4d5e60",
    "chain": "BASE",
    "asset": "USDC",
    "amount": 25,
    "status": "COMPLETED",
    "transactionHash": "0xa1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
    "createdAt": "2026-01-15T09:30:00Z",
    "updatedAt": "2026-01-15T09:30:02Z"
  }
}

Fiat transfer

A fiat-denominated transfer settles in the underlying stablecoin and returns a fiatOrigin block with the original currency and exchange rate.

curl -X POST https://api-staging.venlyfinance.com/v1/accounts/{senderAccountId}/transfers/fiat \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "receiverExternalId": "acct-67890",
    "currency": "USD",
    "amount": 25,
    "description": "Q2 supplier payment",
    "idempotencyKey": "e9f0a1b2-3c4d-5e6f-7a8b-9c0d1e2f3a4b"
  }'

Self-custody senders also need a CONFIRMED permit and a granted allowance before a transfer succeeds — see Approving transfers without gas. Venly-managed accounts don’t.

Step 10 — Track the transfer

Crypto and fiat transfers usually complete synchronously, but you can always fetch the latest state:

curl https://api-staging.venlyfinance.com/v1/accounts/{accountId}/transfers/{transferId} \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

`status`	Meaning
`PENDING`	Accepted, settlement in progress
`COMPLETED`	Final — funds delivered (`transactionHash` populated)
`FAILED`	Final — see `errorMessage`

List all transfers for an account with GET /accounts/{accountId}/transfers plus pagination parameters. Retrying a create with the same idempotencyKey returns the original transfer — no double-spend.

Common pitfalls

IBAN or pay-out blocked on a party that is already VERIFIED

Verification is not the last gate. Check the party’s partner-terms consent — if status is REQUIRED, your customer still has to accept on the hosted page, and no amount of retrying will clear it. Hand them the consentUrl. This one is easy to mistake for a KYC problem because the account looks fully verified.

KYC errors (kyc-not-verified or kyc-required) on transfers, IBANs, or payments

The account is still VERIFICATION_PENDING. Its party must complete verification first — poll GET /accounts/{id} until kycStatus is VERIFIED. (The party’s status being ACTIVE is not enough.)

Self-custody transfer fails even when verified

The customer hasn’t signed the token permit yet, so Venly has no allowance to move funds. Run the permit flow once, then retry.

Address is required for SELF_CUSTODY wallet type

Self-custody accounts must include the customer’s wallet address on creation. Venly-managed accounts must not.

account-not-found on a transfer

The receiverAccountId / receiverExternalId doesn’t resolve to an account in your company. Transfers are account-to-account — both sides must be Venly accounts you own.

Token expired mid-flow

Tokens last 5 minutes. Catch 401, refresh, and retry the original call. Don’t pre-authenticate every request — cache the token.

Next steps

Getting started

The condensed party → account → verify → IBAN flow.

Browse the API reference

Every endpoint, field, and error code.

Permits & allowances

Gasless token approvals for self-custody accounts.

Contact support

Stuck? Get in touch with your accountId and the failing request.

​What you’ll build

​Prerequisites

​Step 1 — Authenticate

​Step 2 — Create a party

​Step 3 — Open an account

​Add a second account holder (optional)

​Step 4 — Get the account verified

​Step 5 — Have the customer accept the partner terms

​Step 6 — View the wallet

​Step 7 — Issue a virtual bank account (IBAN)

​Step 8 — Fund the account

​Option A — SEPA transfer to the IBAN

​Option B — Hosted fiat-to-crypto pay-in

​Step 9 — Send a transfer

​Crypto transfer

​Fiat transfer

​Step 10 — Track the transfer

​Common pitfalls

​Next steps

Getting started

Browse the API reference

Permits & allowances

Contact support

What you’ll build

Prerequisites

Step 1 — Authenticate

Step 2 — Create a party

Step 3 — Open an account

Add a second account holder (optional)

Step 4 — Get the account verified

Step 5 — Have the customer accept the partner terms

Step 6 — View the wallet

Step 7 — Issue a virtual bank account (IBAN)

Step 8 — Fund the account

Option A — SEPA transfer to the IBAN

Option B — Hosted fiat-to-crypto pay-in

Step 9 — Send a transfer

Crypto transfer

Fiat transfer

Step 10 — Track the transfer

Common pitfalls

Next steps