Quickstart - Flinks Connect and API

Flinks Connect is the interface on which your customers will connect their bank accounts. Flinks Connect handles all the complicated bank authentication processes, so you don't have to worry about all the edge cases and error handling.

The end-user interacts with Flinks Connect to provide the credentials that are needed for Flinks to connect to the user's bank account. A successful connection is confirmed when the end-user is redirected to a landing page that's configured in your integration. Alongside the redirect, you will receive a LoginId related to the account that has just been connected.

When this happens, Flinks starts to collect all the data in the background and your backend needs to start the flow in order to receive and consume all these data.

Here are the steps for you to quickly integrate Flinks into your business:

Flinks Connect

Adding the iframe

To embed Flinks Connect into your page, you simply need to add your Flinks Connect private instance URL into an iframe. For this example, we are using the sandbox instance (named toolbox) with a few recommended parameters:

<!-- Flinks Connect -->
<iframe class="flinksconnect" height="760"
        src="https://toolbox-iframe.private.fin.ag/v2">
</iframe>

Configuration

All customizable options for layout and functionalities are controlled by the parameters that are entered directly as URI parameters into the iframe URL.

All available parameters and options are described in Flinks Documentation.

Event Listener

With Flinks Connect it is possible to enable a Javascript Event output which returns different steps taken by the end-user during the Authentication process and errors codes as well.

These events are useful tools for controlling the user experience and for tracing purposes, but using the event listener is optional.

To activate the event listener, you need to add the following script into your page:

<!-- Event Listener -->
<script>
    window.addEventListener('message', function(e) {
        console.log(e.data);
    });
</script>

You will find a list to all of the Events here.

Redirection and LoginId

Once an account is successfully authenticated with the Financial Institution, Flinks Connect will redirect the end-user to the landing page, which was defined in the RedirectUrl parameter. Along with the redirection, you will receive the LoginId (and the accountId if the account selector is enabled), which is the reference from the recently-connected account. This is the required information for you to receive the Financial data later on.

You have two ways to retrieve the LoginId:

1. Directly from the redirected URL

Flinks Connect adds the loginId along with the institution into the landing page url. Example:

https://flinks.com/contact/thank-you/?loginId=c255da7c-d5f8-4182-d96c-08d94d3c33c3&institution=FlinksCapital

1. From the Event Listener

From the Redirect step Object: EXAMPLE:

{step: 'REDIRECT', url: 'https://toolbox-iframe.private.fin.ag/v2/Result/Fl…-4ca6-8782-01ffeb314ccc&institution=FlinksCapital', loginId: '6747ff12-6943-429f-c710-08d9aaed1c78', requestId: '89c77e20-dc45-4f30-9a9c-24059b1d255c', accountId: '226a0a34-7de6-4ca6-8782-01ffeb314ccc', …}

Retrieving the data

There are 2 ways for you to access the data from the connected accounts from your backend. You can retrieve the data through API calls in cached mode, or by using webhooks.

Option #1 - API

Every time you want to retrieve data from a connected account, you need to initiate a new session with Flinks, which means that you will need to generate a RequestId each time, in order to call /GetAccountDetails .

Step 1: /Authorize - Open a new session

To generate a new RequestId, you need to call /Authorize, specifying a LoginId and the parameter MostRecentCached:true, as we're calling the API in Cached Mode.

This endoint will generate you a new RequestIdinto the response:

Step 2: /GetAccountsDetail - Requesting the data

Using the new RequestId from step1, you can check if our data is ready to be returned by calling /GetAccountsDetail:

In case you are making use of one of our Account Selection features, you must include the accountId fetched in the Redirect event through the AccountsFilter, as below:

Endpoint call response:

Important: In case you receive the FlinksCode OPERATION_PENDING, it means that the process dispatched by Flinks Connect is not yet completed. In this case, refer to this article in order to learn about the Asynchronos Flow.

Option #2 - Webhooks

Another way to receive data is by setting up a webhook endpoint in your backend.

Instead of calling the API to receive the JSON with the financial data, Flinks will callback your endpoint with the JSON result of the connected accounts as soon the data extraction process is complete.

For us to configure your private instance with your webhook endpoint address, please contact Flinks Support team.

Observation: It's not possible to test webhooks integration using a Sandbox environment

HMAC signature

One way to verify the authenticity and the integrity of the requests coming to your server is to use a secret token to validate the information that you receive from the webhook's callbacks.

If this feature is enabled, Flinks webhook callback will be sent with a key so you can validate the authenticity and the integrity of the information received.

Flinks uses HMAC with SHA-256 encryption to generate a validation key that will be sent within the HTTP response using the header flinks-authenticity-key.

The secret key used to do the encryption will be provided and configured on your instance when we setup your webhook address.

Authenticity and Integrity

In order to verify the authenticity and the integrity of the received webhook callback, you’ll need to combine your secret key with the received JSON response. Using the technology of your choice:

• Retrieve and store the content of the header flinks-authenticity-key
• Using the ASCII encoding format, convert the secret key provided to you into a byte array.
• Using the same ASCII encoding format, convert the serialized JSON response you received into a byte array.
• Using HMAC-SHA256 encryption implementation in your language of choice, using the secret key as the encryption key, compute a hash of your serialized JSON response.
• Convert the obtained hash byte into an Base64 string.
• Compare the result of the Base64 string and the flinks-authenticity-key received in the header response.
• If the Base64 string matches the flinks-authenticity-key, you have a valid message!

Get Support!

FAQ and technical solutions can be found at our Flinks Help Portal!

Any questions can be asked to our support team by sending an e-mail to [email protected].