Transactions

A transaction is a single money movement on an Account — a card purchase,
a transfer, a fee. Transactions are enriched with a category, a merchant name,
and (for card purchases) installment details. For how transactions sit under
accounts and connections, see Core Concepts.

ℹ️

Transactions come from banks the user has linked in the Financy UI

(connections cannot be created via the API). No linked bank means no
transactions — see Connections.

All endpoints require a Bearer token — see Authentication. Failed requests
return the standard error shape — see Errors.

List transactions

GET https://api.open-finance.ai/v2/data/transactions

Request

curl "https://api.open-finance.ai/v2/data/transactions?accountId=01J8ACC...&dateFrom=2026-01-01&limit=50" \
  -H "Authorization: Bearer <accessToken>"

Response

{
  "nextPage": "eyJTSyI6...",
  "items": [
    {
      "id": "01J8TX...",
      "SK": "TX#01J8TX...",
      "accountId": "01J8ACC...",
      "providerId": "max",
      "type": "NORMAL",
      "merchantName": "Shufersal",
      "amount": {
        "chargedAmount": { "amount": -239.9, "currency": "ILS" },
        "originalAmount": { "amount": -239.9, "currency": "ILS" }
      },
      "description": { "description": "SHUFERSAL DEAL", "additionalInfo": "" },
      "category": { "main": "FOOD_&_DRINKS", "sub": "GROCERIES", "categorizedBy": "MCC" },
      "date": {
        "transactionDate": "2026-01-04",
        "bookingDate": "2026-01-05",
        "valueDate": "2026-01-05"
      },
      "balancePerEndDay": 4210.55
    }
  ]
}

Page through results by passing the returned nextPage cursor on the next call.

Transaction fields

Categories

Each transaction is categorized with a two-level, uppercase-enum taxonomy:

"category": { "main": "FOOD_&_DRINKS", "sub": "GROCERIES", "categorizedBy": "MCC" }

• main — the high-level group, e.g. FOOD_&_DRINKS, TRANSPORT, SHOPPING,
  HOUSEHOLD_&_SERVICES, HEALTH_&_BEAUTY, LEISURE, FINANCE, OTHER
  (income uses its own groups such as SALARY, PENSION, BENEFITS).
• sub — a specific label nested under main, e.g. GROCERIES, RESTAURANT,
  CAR_&_FUEL, PUBLIC_TRANSPORT.
• categorizedBy — how it was categorized, e.g. MCC (merchant category code).

Expenses and income are separate taxonomies, so the same name (e.g.
FINANCE, OTHER) can appear in both. When a user re-categorizes a transaction,
the override is on changedCategory (same { main, sub } shape); the original
system value stays on category.

Get a transaction

GET https://api.open-finance.ai/v2/data/transactions/{SK}

Pass the SK (not id) from the list response:

curl "https://api.open-finance.ai/v2/data/transactions/TX%2301J8TX..." \
  -H "Authorization: Bearer <accessToken>"

💡

SK can contain characters like # — URL-encode it (# → %23) when

putting it in the path.

Best practices

• Always page. Loop on nextPage until it comes back empty; don't assume a
  single call returns everything.
• Bound with dates. Combine dateFrom / dateTo with limit to keep pages
  small and predictable.
• Skip duplicates by leaving includeDuplicates at 0, or filter on
  isDuplicate yourself if you request them.

Next: manage the payees you pay to in Merchants (Payees).