Skip to navigation

How to read this reference

The calls of a widget session, in the order you make them
View as Markdown

Every page under this heading is generated from the running service. What a generated page cannot tell you is which call comes first — so this one does, in about a minute.

New here? This page is the map, not the introduction. What Financial Rider is, what your customer goes through and what comes back are on its overview — and what every flow shares, one step further, on What is a flow.

Financial Rider overview

One-shot or recurring access

Decide it before the first call, because it is a setting of that call:

One-shot. The session reads your customer’s banks once, while they are in the widget: they consent, connect, and you read what came back. Nothing stays connected afterwards — no token, no later refresh — so the happy path below is the whole integration, start to end.

The happy path

Recurring access. Add tokenized_access when you create the session, and your backend keeps reading those banks afterwards, on its own schedule — through the Direct Executions API, with no widget and no customer in front. The session is the first connection; every read after it is server to server.

Recurring Access

The happy path

1

Create the session

Create Session from your backend, with your application secret — naming the banks to offer, or the one bank to connect, and tokenized_access for recurring access. You get a session_id and the URL to open.

2

Send your customer to the widget

They consent, pick their bank and sign in to it — the journey is the widget’s job, not yours. Redirects & Completion covers where they land when it is over.

3

Wait for something to happen

Register a webhook and we tell you when consent is given and when the session ends; or ask for the session state.

4

Read what came back

Get Session Results carries the financial position from every bank connected, and Download Attachments the documents a bank delivered with it.

5

Keep the access — recurring access only

Exchange a ticket once per connection the results list, and store each token by its token_id — a bank already connected comes back as the same token_id, renewed: true. Every later read is Initiate with a token, then the results of that execution. All of these are the Direct Executions API, server to server with your application secret: this API’s part ends with the session. Recurring Access has both phases in full.

Two things worth knowing before you build

The webhooks can travel encrypted. A session created with an aes_key sends every webhook with its data encrypted under that key, so what reaches your endpoint is readable only by you. The results you read with your application secret travel over TLS, like every call.

The session key

The person is in the loop. Unlike a direct execution, the credentials never reach you: your customer types them into the widget, and only they can answer what their bank asks. That is the whole point of a flow, and it decides what you have to build around it.

Their journey

Everything that holds for every endpoint — the X-APP-SECRET header, the base URLs, the error shape and the rate limits — is stated once, not repeated on each page.

Using the API