Skip to content

Flanks Link

Links are the mechanism to add credentials and, therefore, gather their data. Each link has a unique URL, and allows the users accessing it to select a bank and add their own credentials for that institution.

They are designed to be integrated with your Application via http redirects.

The most common flow using Flanks Links is:

sequenceDiagram
  autonumber
  Your Application->>Flanks Link: Redirect user
  Flanks Link->>Flanks Link: Select bank
  Flanks Link->>Flanks Link: Do login
  Flanks Link->>Flanks Link: Optionally, enter SCA
  Flanks Link->>Your Application: Redirect user (with link code or with error)
  1. The user starts in your Application, and you redirect them to a Flanks Link.
  2. The user selects an institution from the list of available ones.
  3. The user adds their username and password.
  4. If needed, the user solves a second-factor challenge, to validate credentials ownership.
  5. Once the process is finished (with success or failure) the user is redirected back to your application.

Each link has a unique URL. Every time anyone loads that URL, they will be able to connect new credentials to Flanks. You can get the Link's URL from the Flanks Platform.

Configuration

Every link can be configured by editing the query string and adding parameters.

A naked URL for a Link looks like this: 

https://platform.flanks.io/link?token=<TOKEN>

You can add parameters to the URL to configure the Link. In this example, we're setting param1 to 42 and param2 to flanks: 

https://platform.flanks.io/link?token=<TOKEN>&param1=42&param2=flanks

Configure Bank

If you set the parameter bank to a valid id for an institution, the user won't be able to select the bank from a list. Instead, the login screen for that institution will be directly shown.

This is useful when, in your application, you already let the user choose the entity.

Example: 

https://platform.flanks.io/link?token=<TOKEN>&bank=testbank

You can get the list of banks using the Get Entities endpoint.

Configure Language

If you set the parameter language you can change the language used (which, by default, is Spanish).

The list of available languages are:

  • de: German
  • en: English
  • es: Spanish
  • fr: French
  • it: Italian
  • pt, pt_pt: Portuguese from Portugal
  • pt_br: Portuguese from Brazil
  • sv: Swedish

Example: 

https://platform.flanks.io/link?token=<TOKEN>&language=en

Configure ExternalId

An ExternalId is a value identifier set by yourselves that has no meaning for Flanks

If you set the parameter external_id, their value will be included in the Credentials Status. This can be useful if you have an internal code for each user. Every credential added using this link will be associated with this external_id.

Example: 

https://platform.flanks.io/link?token=<TOKEN>&external_id=user123

Configure Error Behaviour

See Tracking Back Errors via Redirect

Start SCA Flow

When credentials cannot continue without a manual intervention to provide a second factor they have a sca_token. This sca_token is automatically created by Flanks when needed.

With this one-time token you can make the link ask for the SCA to the final user. The username and password will not be asked, because they are already safely stored.

To trigger the SCA Flow, you have to provide both the sca_token and the bank parameters. Both can be found in the Credentials Status.

Example: 

https://platform.flanks.io/link?token=<TOKEN>&sca_token=<SCA_TOKEN>&bank=testbank

Start Reset Flow

When credentials are blocked they have a reset_token. They need a manual intervention to provide the username and password, because the ones already stored don't work. This reset_token is automatically created by Flanks when needed.

With this one-time token you can make the link ask again for the username and password to the final user.

To trigger the Reset Flow, you have to provide both the reset_token and the bank parameters. Both can be found in the Credentials Status.

Example: 

https://platform.flanks.io/link?token=<TOKEN>&reset_token=<RESET_TOKEN>&bank=testbank

Start Transaction Flow

Some institutions require an extra SCA validation to provide transactions older than 90 days. To start the Transaction Flow you'll need to manually force a transaction_token using the Force SCA, Reset or Transaction Token endpoint.

With this one-use token you can make the link ask for the SCA to the final user. The username and password will not be asked, because they are already safely stored.

Example: 

https://platform.flanks.io/link?token=<TOKEN>&transaction_token=<TRANSACTION_TOKEN>&bank=testbank

Extra Parameters

Any other parameters that you add to a Link URL will be returned inside the extra field when you Exchange Link Code for Credentials Token.

Example: 

https://platform.flanks.io/link?token=<TOKEN>&one_param=1&other_param=2

Links are used to add credentials to Flanks. These credentials are tested against the real Financial Institution's websites before adding them to Flanks.

This is the current list of errors that the Link can react to:

Error Code

Description

INVALID_CREDENTIALS

The provided credentials are invalid.

INVALID_SCA

The provided SCA is invalid.

CREDENTIALS_ALREADY_EXIST

The credentials provided already exist in our system.

SCA_TYPE_NOT_ALLOWED

The two-factor authentication method provided is not allowed on the account.

USER_INTERACTION_NEEDED

The account has some pending checks/tasks that need the user to access the official website and complete them.

ABORTED_BY_USER

This is a special error code. If any other error happens and the redirection is not configured for said error, the user will have an "EXIT" button if rollback for ABORTED_BY_USER is set. When pressing the "EXIT" button, the user will be redirected like any other kind of error, but the error code will be ABORTED_BY_USER.

INTERNAL_ERROR

An unexpected error from the Flanks API.

Tracking Back Errors via Redirect

By default, these errors will be shown on the screen, but the user will not be redirected.

If you want to be notified in your redirect_uri, you need to add the rollback parameter to the link URL. Then, if an error occurs in the connection process, the user will be redirected and will include in the parameters the error key.

You can specify which Error Codes you want to receive, and all the others will be handled in our platform without a redirect.

For example, you can choose to redirect only INVALID_CREDENTIALS errors:

https://platform.flanks.io/link?token=<TOKEN>&rollback=INVALID_CREDENTIALS

Or redirect multiple errors: 

https://platform.flanks.io/link?token=<TOKEN>&rollback=INVALID_CREDENTIALS,INVALID_SCA

You can also rollback=true to redirect all the errors.

If you added extra parameters as described in Using the Platform, the request to your redirect URI will include both the error parameter and your extra parameters. For example:

https://redirect_url?error=INVALID_CREDENTIALS&extraparams=value