Getting Started with Financy

The Financy API does two things on behalf of your users:

• Read financial data — their connected accounts and transactions.
• Initiate payments — open-banking payments, hosted by Financy or driven directly.

ℹ️

The API is available on every paid Financy plan: Starter, Pro, and Ultra.

Free organizations must upgrade before their API credentials can use these endpoints.

📘

New here, or unsure what a connection is versus an account? Read

Core Concepts first — it defines every entity and how they relate.

Base URLs

Authentication in one line

Every API request (except POST /oauth/token itself) must carry an access token:

Authorization: Bearer <accessToken>

You obtain that token from POST /oauth/token using your clientId,
clientSecret, and the end-user's userId. The token acts on behalf of that
one user. See Authentication.

⚠️

Data and payment endpoints require a paid Financy plan (Starter,

Pro, or Ultra). A valid token on the Free plan returns 403 with
NOT_AVAILABLE_ON_PLAN — see Errors. Credentials live under
Settings → API in the Financy app.

The foundation: a linked bank

Everything below depends on the user having linked a bank.

⚠️

Banks are linked only through the Financy UI — there is no API to create a
connection. The user completes the hosted consent journey in Financy; once

they do, a Connection exists and your token can read its data and act on it.
The API lets you list, read, refresh, and delete connections, but never create one.

Need to create connections programmatically — for example, to aggregate
your customers' data at scale? That's available on the Open Finance
platform (our B2B product). Contact us to get access.

Track 1 — Read financial data

Once a bank is linked, walk the data model top-down:

1. Connections — the user's linked banks. Start here to find a connectionId.
2. Accounts & Balances — the accounts on a connection and their balances.
3. Transactions — the money movements on an account, with date filters and pagination.

Track 2 — Initiate a payment

⚠️

Payments also need a linked bank: the payment must involve one of the user's

connected accounts, as the payer (debtor) or the payee (creditor). See
Create a Payment.

Financy plan fees apply to new ILS payments created by either integration style,
but only after the payment succeeds: Starter 0.4% (minimum ₪0.50), Pro 0.3%
(minimum ₪0.50, maximum ₪3.50), and Ultra 0.2% (minimum ₪0.50, maximum
₪2.70). Failed and canceled payments are not charged.

Creating a payment is a four-step flow, in one of two integration styles:

A. Hosted (recommended) — you create the payment and redirect the user to the
payUrl we return; Financy hosts bank selection and authentication.

1. POST /oauth/token → accessToken
2. POST /v2/payments → { id, payUrl }
3. Redirect the user to payUrl
4. Poll GET /v2/payments/{paymentId}/status until a final status

B. Direct API — you select the bank yourself and get the bank's authentication URL.

1. POST /oauth/token → accessToken
2. POST /v2/payments → { id }
3. POST /v2/pay/open-banking-init with paymentId + providerId → { scaOAuth }
4. Redirect the user to scaOAuth, then poll the status

Track 3 — CLI and AI agents

The same read surface is available without writing HTTP yourself:

• The open-source financy CLI wraps connections, accounts, and
  transactions, adds a freshness rollup and stable exit codes, and ships a
  local MCP server for agents on your machine.
• A remote Financy connector lets an AI host call the read endpoints with
  an OAuth token (no API key on the agent machine). It cannot pay, delete, or
  refresh.

Reference data

📘

These guides walk each step with real examples. For every field on every

endpoint, see the API Reference.