Vezmo App

Accounts API

Accounts API

Read your Vezmo accounts from your own systems: accounts and balances, transactions, monthly statements and events. This phase is read only: no key can move money, add a recipient, approve anything or change keys, the team or webhook endpoints.

Vezmo switches the Accounts API on per business. Until it is on, every call answers 403 api_access_not_enabled; ask from Settings › Developers › Accounts API in the dashboard.

Endpoints

  • POST /oauth/token — swap a key for a 15-minute access token (below).
  • Accounts and balances: GET /accounts, GET /accounts/{id}, GET /balances (accounts.read).
  • Transactions: GET /transactions, GET /transactions/{id} (transactions.read).
  • Statements: GET /statements, GET /statements/{id} as JSON, CSV or PDF (statements.read).
  • Events and webhooks: GET /events, GET /events/{id} (events.read), and signed webhooks.
  • Sandbox: POST /simulations/… with a test key.

Base URL: https://api.vezmo.com/api/v1, for test and live keys alike. The key decides the data. The OpenAPI 3 description of these routes is at https://api.vezmo.com/api/v1/openapi.json, for code generators and API tools.

Access tokens

POST /oauth/token is the OAuth 2.0 client-credentials grant (RFC 6749), so any OAuth library works. Authenticate with the key ID and secret one way: HTTP Basic (client_secret_basic), or client_id and client_secret in the body (client_secret_post). The body is form-encoded or JSON. Each endpoint needs its Accounts API permission on the key (a key holding only them has an ID like vzm_live_ro_… or vzm_test_ro_…).

HTTP Basic
curl -X POST https://api.vezmo.com/api/v1/oauth/token \
  -u "$VEZMO_KEY_ID:$VEZMO_SECRET" \
  -d grant_type=client_credentials

An optional scope (space-separated) narrows the token to some of the key's permissions; the token can then use only those, and only while the key still holds them.

In the body, with scope
curl -X POST https://api.vezmo.com/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "vzm_live_ro_4Hq9ZbT1mK2xPv7d",
    "client_secret": "'"$VEZMO_SECRET"'",
    "scope": "accounts.read transactions.read"
  }'
200 OK
{
  "access_token": "eyJhbGciOiJFUzI1NiIs…",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "accounts.read transactions.read"
}
  • The token lasts 15 minutes (expires_in: 900). There is no refresh token: ask again. The key's status, IP limits and your business's access are checked again on every call, so revoking a key stops it at once.
  • A secret found in public code (GitHub secret scanning): a live key is revoked at once and its tokens end; a test key can no longer run simulations (403 key_leaked) and still reads test data until you revoke it. Every admin of your business is told.
  • 10 tokens a minute per key. Failed exchanges: 5 a minute per IP address (a correct secret always gets through).
  • Answers are OAuth's own shape. Errors: invalid_request, unsupported_grant_type, invalid_client (401, with WWW-Authenticate), invalid_scope, and unauthorized_client with code ip_not_allowed or business_api_paused. Always Cache-Control: no-store.
401 invalid_client
{
  "error": "invalid_client",
  "error_description": "The key ID or secret is wrong, or the key is switched off, revoked or expired."
}
Node.js
// Node 18+: one token, reused until a minute before it ends.
let cached = { token: null, until: 0 };

export async function accessToken() {
  if (cached.token && Date.now() < cached.until) return cached.token;
  const res = await fetch("https://api.vezmo.com/api/v1/oauth/token", {
    method: "POST",
    headers: {
      Authorization: "Basic " + Buffer.from(`${process.env.VEZMO_KEY_ID}:${process.env.VEZMO_SECRET}`).toString("base64"),
      "Content-Type": "application/x-www-form-urlencoded",
    },
    body: "grant_type=client_credentials",
  });
  if (!res.ok) throw new Error(`Token refused: ${res.status} ${await res.text()}`);
  const body = await res.json();
  cached = { token: body.access_token, until: Date.now() + (body.expires_in - 60) * 1000 };
  return cached.token;
}

Your first call

Request
curl https://api.vezmo.com/api/v1/balances \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Vezmo-Version: 2026-11-14"

Versions

Vezmo-Version: 2026-11-14 is the only version today. Your business is pinned to the newest version at its first call; calls without the header use the pin, and a header overrides it for that call only. Every answer echoes Vezmo-Version. An unknown version is 400 validation_failed with field: "Vezmo-Version".

Conventions

  • Envelope: { success, data, meta, requestId, timestamp }; errors { success: false, errors: [{ code, message, field?, help }], requestId }.
  • Money: integers in the currency's smallest unit with an ISO currency (125000 + USD = US$1,250.00).
  • Times: RFC 3339, UTC. Time filters must carry a zone, like 2026-10-01T00:00:00Z.
  • Ids: acct_, txn_, stmt_, evt_, inc_, tr_. Another business's id answers 404.
  • Masking: account numbers show the last 4 (••••1234). Payer names are shown.
  • Filters: a parameter an endpoint doesn't take is 400 unsupported_filter, never ignored.
  • Caching: every answer is Cache-Control: no-store.

Pagination

Lists are newest first. limit takes 1–100 (default 25). When meta.hasMore is true, pass meta.nextCursor as startingAfter. A cursor from another list or business is 400 validation_failed (field: "startingAfter").

Next page
curl "https://api.vezmo.com/api/v1/transactions?limit=50&startingAfter=txn_cm3k9q2xv0001" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# meta: { "hasMore": true, "nextCursor": "txn_cm3k9p7aa00ff" }

Errors

403 insufficient_scope
{
  "success": false,
  "errors": [
    {
      "code": "insufficient_scope",
      "message": "This API key doesn't have the statements.read permission.",
      "scopes": ["statements.read"],
      "help": "https://user.vezmo.com/docs/v1/errors#insufficient_scope"
    }
  ],
  "requestId": "1b1f55e8-b214-48a9-92f1-d6aad8f7a312"
}

Every code is explained on Errors, and each error's help links straight to it.

Rate limits

  • Every answer carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Request-Id. A 429 adds Retry-After and Vezmo-RateLimit-Reason.
  • Your key's own per-second limit applies, as on the rest of the API.
  • Statements: 30 a minute per key, and 60 new statements a minute per business (each server enforcing its share; a month already made is free).