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, 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 connection with status ACTIVE refreshes daily; a COMPLETED
  connection was a one-time fetch and won't update.
• A connection exposes lastFetchedDataDate (when data was last pulled) and
  startDate (the earliest date transactions were collected from).
• 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.

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