Skip to navigation
Sessions Management

Create Session

View as Markdown

Open a Financial Rider session for one of your customers, and get the widget_url to send them to.

Choose how the session finds your customer’s bank:

You sendThe session
markets and entity_typesOffers every bank of those markets and kinds your application may use, the most used first. Your customer picks; with max_connections (1 to 3) they may connect several.
engine_referenceConnects that one bank, which must be able to run right now. Your customer chooses nothing; max_connections is 1.

Sending both is refused (422). Values you leave out come from your application’s defaults, when it has them. The consent screen is not chosen here: it is your application’s, as agreed for it.

Also in the request:

  • executions_features — what to read: the customer profile, accounts, cards, deposits, loans, the investment families, direct debits.
  • engines_layout, priority_engines, featured_engines — how the selection draws the banks for this session: the first ones as rows of tiles, yours listed first in your order, up to three highlighted. A field you send is used as sent — an empty list orders nothing, an empty dictionary highlights nothing —; one you leave out takes your application’s setting.
  • fixed_parameters — what you already know about your customer: user_identification (a Spanish NIF or NIE) and user_email. A document that asks for the signer’s identity starts with it, and the signer must assert that same identity. It is never used as a bank username.
  • aes_key — encrypts the data of every webhook; without it, events travel without data.
  • tokenized_access — answers with a ticket to exchange each connection for a reusable credentials token, at Exchange a ticket on the Direct Executions API; refreshing is a server-to-server Initiate with a token, with no widget. The session then offers only the banks that can keep credentials (tokenized_access on the engine catalogue), and a named bank that cannot is refused.
  • completion_mode / completion_url — what the experience does when the session ends; a return URL must be one of your application’s.
  • hooks_extra_data — values echoed into your webhook URLs.

Why a session is refused:

  • 400 — nothing your application may use matches the filters (no_engines_available), nothing that matches can keep credentials when the session asks for tokenized_access (no_engines_available_for_tokenized_access), or the return URL is not one of yours.
  • 403 — a production session from an application that is not in production, or without the capability it needs.
  • 404 — the named bank does not exist.
  • 422 — the request contradicts itself, or a named bank is not one this session can use — among the reasons, engine_not_available_for_tokenized_access.
  • 503 — the named bank cannot run right now; the detail says why.

This endpoint needs to be executed with an app secret, so should always be used in server side without exposing the secret to customers.

Authentication

X-APP-SECRETstring
Application Secret

Request

This endpoint expects an object.
customer_idstringRequired1-64 characters
Your own identifier for the end user, up to 64 characters. It comes back with every read and every event of this session.
settingsobjectRequired

How the session runs: what it reads, from where, and how the results reach you.

fixed_parametersobjectOptional
What you already know about the end user, to be corroborated on their signatures.
date_limitstringOptionalformat: "datetime"

When the session must close if it is still open. Absent: 12 hours after creation; it is never later than 72 hours after creation, and never before it.

Response

200 OK
Flow Session created successfully

session_idstringformat: "object-id"
The identifier of the new session. Every read of the session uses it.
widget_urlstring

Where to send the end user: open it in an iframe, a new tab or a web view.

session_tokenstring

The end user’s credential for this session, already embedded in widget_url. It lets the widget act on the session; it never reads its results.

ticketstringOptional=64 characters

Present only when the session asked for tokenized_access. Exchange it, together with the id of each connection in the results, for a reusable credentials token — at Exchange a ticket, on the Direct Executions API. It is shown here and nowhere else.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error
500
Internal Server Error
503
Service Unavailable Error