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.

📘

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.

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, 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.

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

Reference data

📘

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

endpoint, see the API Reference.