Financial Rider Flow

Financial Rider is the flow that connects your customer’s banks — with their consent — and gives you what those banks hold: accounts and their movements, cards, deposits, loans, investments and direct debits, read from each bank and delivered as one structured document. Like every flow, it works out of the box: there is nothing to build between the session you open and the data you receive.

Your customer does it in a secure experience hosted by INFONITE: they consent, pick their bank, sign in to it — with the bank’s own login and whatever second factor it asks for — and, when your session allows it, connect a second and a third one. Their banking credentials are typed into our widget and never reach your servers.

One-shot or recurring access

The first decision of an integration: whether you need your customer’s banks once, or for as long as you work with them.

Recurring access is one setting at Create Session: tokenized_access. Each bank your customer connects keeps its credentials tokenized, and every later read is a server-to-server call — Initiate with a token, on the direct executions API — with no widget and no customer in front. Not every bank’s engine supports it — each one says so in tokenized_access, on List your engines —, and a session with recurring access offers only the banks that do. Recurring Access walks through both phases.

Use cases

What a connected bank gives you, and what it is used for. Each one says whether it is a one-shot read, needs recurring access, or works both ways.

Every one of them is a set of features you name when you create the session — customer_information_read, accounts_read, cards_read, deposits_read, loans_read, investment_accounts_read, stocks_read, funds_read, pensions_read and direct_debits_read —, and every record they return is described field by field in the banking data models.

Choosing the banks

• Let your customer choose. Send the markets and entity_types you work with — corporate for business banking — and the features you need. INFONITE resolves the banks your application may offer — the most used ones first — and your customer picks theirs. With max_connections (up to 3) they may connect more than one, and the session merges what every bank returned into one answer.
• Name the bank. When you already know where your customer banks, send its engine_reference instead of the filters. The session connects that one bank and your customer chooses nothing.

Either way, INFONITE decides which connection technology reaches each bank: you never maintain a list of engines. The fields, their limits and every refusal are in Create Session.

What your customer goes through

Integration Lifecycle

Knowing when a session is finished

A session ends in one of these ways — and only a session that connected at least one bank has results:

When your customer leaves from the widget, the ended webhook carries user_feedback: reason, the option they chose — took_too_long, entity_not_listed, missing_credentials, distrust, unclear_steps or other —, and feedback, what they wrote, as they wrote it.

What comes back

Get Session Results — and the ended webhook, when it carries data — returns:

• data — the financial position, in the same shape as the one direct executions return: one list per family you asked for and the customer profile. A family you did not ask for is absent.
• connections — each bank connection that finished, and the engine that ran it. A connection still running is never in data: what you read is only what finished. With recurring access, these are the ids each ticket exchange takes.
• consent — what your customer agreed to and the proof of it.
• messages — what the session found while it ran, below.

When the banks do not agree on who your customer is

The customer profile is the one the first connected bank returned. Your customer chooses their own credentials for each bank, so two banks may describe different people — a shared account, a relative’s login. When another connected bank disagrees, the session raises a crossed_identity flag at ["data", "customer", "profile"]: the profile is still the first one, and the flag is what tells you the banks were not unanimous.

A flag never means something failed on our side: it is something about the person or the data that deserves a decision on yours, so route it to whatever already decides when a case needs a second look. messages, its four types and its fields are described in Get Session Results.

Sandbox and production

A session created with sandbox: true connects demo banks that answer with test data — Demo Bank, in Spain — and any application may open one, recurring access included. A production session never offers a demo bank.

Payload Decryption (AES-256-GCM)

When an aes_key is provided at session creation, webhook payloads are encrypted. The data field contains a string prefixed with aes:::

{
  "data": "aes::U2FsdGVkX19..."
}

1. Remove Prefix: Strip the aes:: prefix from the string.
2. Decode Base64: Decode the remaining string to retrieve the raw bytes.
3. Extract Parts: the first 12 bytes are the IV, the last 16 the authentication tag, everything between them the ciphertext.
4. Decrypt: Decrypt using AES-256-GCM with your session key (aes_key), the extracted IV, and the Tag.

Without an aes_key, no webhook carries data at all: your customer’s financial records never travel in the clear, and you read them from Get Session Results.