Core Concepts

This page defines every entity in the Financy API and how they relate. Read it
once and the rest of the guides will make sense: each other guide is the
"how-to" for one of the entities described here.

The big picture

Financy sits between your application and a user's banks. A user links one or
more banks (each link is a Connection); each connection exposes one or
more Accounts; each account has a history of Transactions. Separately,
you can initiate Payments out of a user's bank and save Merchants
(payees) to pay to.

User (identified by userId on your token)
│
├── Connection            one per linked bank — created ONLY in the Financy UI
│   └── Account           a product inside that bank: checking, card, savings, loan, securities
│       └── Transaction   a single money movement on that account
│
├── Payment               an open-banking payment you initiate on the user's behalf
└── Merchant              a saved payee you can attribute payments to

Provider                  reference data: the definition of a bank/card issuer
                          (referenced by connections, accounts, transactions, and payments)

Two independent capabilities sit on top of this model:

• Read financial data — walk Connections → Accounts → Transactions.
• Initiate payments — create a Payment and send the user to their bank to approve it.

Both require the user to have linked at least one bank first.

Entities

Provider

A provider is the definition of a bank or card issuer that Financy
supports (Bank Hapoalim, Leumi, Max, Isracard, …). It is reference data — the
same for every user, not owned by anyone. You reference a provider by its
providerFriendlyId (e.g. hapoalim) wherever a bank must be named: when
restricting a payment (providerIds), initiating a direct payment
(providerId), or filtering data. Guide: Providers & Branches.

Connection

A connection represents one bank a specific user has linked — the
consent/relationship that lets Financy read that bank's data and initiate
payments from it. Think of it as "this user's authorized link to Bank X."

• Created only in the Financy UI, never via the API — linking requires the
  interactive bank consent journey. The API can list, read, refresh, and
  delete connections, not create them. (Programmatic creation is available on
  the Open Finance B2B platform — contact us.)
• Identified by id (used elsewhere as connectionId).
• Belongs to a user; references a provider via providerId.
• Carries a status (e.g. ACTIVE, EXPIRED), a mode (PSD2 open banking,
  or PLAID), an expiryDate (when consent lapses), and counts of what it
  contains: accounts, cards, savings, loans, securities, transactions.

Guide: Connections.

Account

An account is a single financial product inside a connection — one
checking account, one credit card, one savings account, one loan, or one
securities account. A connection usually exposes several accounts.

• Identified by id (used elsewhere as accountId).
• Belongs to a connection (connectionId) and a provider (providerId).
• Has an accountType: CHECKING, CARD, LOAN, SAVINGS, or SECURITY.
• Carries its current balances (an array of { amount, currency }).

Guide: Accounts & Balances.

Transaction

A transaction is a single money movement on one account — a card
purchase, a transfer, a fee, an installment charge.

• Identified by id, and by SK — use SK to fetch a single transaction.
• Belongs to an account (accountId), a connection (connectionId), and a
  provider (providerId).
• Carries amount (chargedAmount and originalAmount), a category
  ({ main, sub }), date (transactionDate / bookingDate / valueDate),
  merchantName, and — for installment purchases — installments
  ({ number, total }).

Guide: Transactions.

Payment

A payment is an open-banking payment you initiate on the user's behalf —
an action, not stored bank data. You create it, the user approves it at their
bank, and it settles.

• Identified by id (used elsewhere as paymentId).
• Requires a Connection. To make or receive a payment, the user must have a
  linked bank, and one side of the payment must be a connected account — the
  debtor (paying from it) or the creditor (receiving into it).
• References the chosen bank via providerId, and optionally a saved payee via
  merchantId.
• Moves through ISO 20022 statuses (INIT → RCVD → … → ACSC/ACCC or
  RJCT) on a rail given by service: masav (default, under 1M ILS), zahav
  (high-value, over 1M ILS), or fp (same-bank transfers).

Guides: Create a Payment, Initiate a Payment (Direct), Payment
Status, Payment Statuses & FAQ, Payment Webhooks.

Merchant

A merchant is a saved payee — a party you attribute payments to, so you
don't repeat their bank details on every request.

• Identified by id (used elsewhere as merchantId).
• Referenced by a payment via merchantId.

Guide: Merchants (Payees).

Connection vs. Account — the key distinction

These are the two most-confused terms, so to be explicit:

In short: a connection is the relationship with a bank; an account is one
account at that bank. You never create either via the API for data — both come
into existence when the user links the bank in the Financy UI.

How the entities are linked (identifiers)

Every "get one" endpoint takes the entity's own id; child entities carry the ids
of their parents so you can filter and join.

Practical joins:

• List a connection's accounts: GET /v2/data/accounts?connectionId=…
• List an account's transactions: GET /v2/data/transactions?accountId=…
• Attribute a payment to a payee: set merchantId on POST /v2/payments.

How data gets there, and how fresh it is

• Data originates from the bank at link time and is refreshed in the
  background — it is a snapshot from the last fetch, not fetched live on each
  request. A COMPLETED connection was a one-time fetch and will not
  update. An ACTIVE connection is on the automatic schedule below.
• Automatic refresh ticks every 6 hours (Asia/Jerusalem, starting in the
  morning). Each plan spends its daily allowance across those ticks: once a
  day (Free / Starter, morning only) or every 6 hours (Pro, and Starter
  with extra refresh slots). On-demand refresh is separate — see
  Connections.
• A connection exposes lastFetchedDataDate (day-granular last successful
  data date), lastFetchedAt (ISO timestamp of the last completed fetch
  attempt, success or error — poll this after an on-demand refresh), and
  startDate (earliest collected transaction date).
• The same real-world account can appear through more than one link; such
  records are flagged isDuplicate, and list endpoints hide them unless you pass
  includeDuplicates=1.
• A connection's consent has an expiryDate; once it lapses (status EXPIRED /
  REVOKED), the user must reconnect in the Financy UI before data updates or
  payments resume.

Identity: the token, the user, and the org

• Your API key is an OAuth2 client-credentials credential (clientId +
  clientSecret). You exchange it for an access token, passing the end-user's
  userId.
• The resulting token acts on behalf of that one user — every data and
  payment call is scoped to that user's connections. Use a separate token per
  user. Your organization (orgId) is carried in the token's claims.
• Connector tokens (see CLI & AI Agents) are a different credential: they
  identify the Financy user who connected an AI client, not an API key, and
  cannot select another userId.

See Authentication for the token exchange, and Errors for the common
error shape every endpoint returns.