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:

xxxxxxxxxx
































































































<iframe src="https://toolbox-iframe.private.fin.ag/?demo=true&redirectUrl=https://flinks.io/contact/thank-you&innerRedirect=true&theme=light&consentEnable=true&customerName=FinTech&backgroundColor=f7f7f7&foregroundColor1=000000&desktopLayout=true&headerEnable=false&institutionFilterEnable=true">
</iframe>















































































Configuration

All customizable options for design 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.

In this example the following parameters were used:

ParameterValueDescription
demotrueEnables the Dummy Institution Flinks Capital into the Institution Selection menu
redirectUrl (mandatory)https://flinks.io/contact/thank-youDefines the landing page URL for Flinks Connect redirection
innerRedirecttrueSets Flinks Connect to redirect only the content within the iframe
themelightEnables the Light theme
consentEnabletrueEnables the Consent Page
customerNameFinTechSets the brand's name for the Consent Page
backgroundColorf7f7f7Sets the background color hex value
foregroundColor1000000Sets the foreground #1 color hex value
desktopLayouttrueEnables the browser responsive design for the Institution Selection Menu
headerEnablefalseRemoves header text and image from the Institution Selection Menu
institutionFilterEnabletrueEnables the Light theme


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:

xxxxxxxxxx
































































































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















































































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, 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:

xxxxxxxxxx
































































































https://flinks.io/contact/thank-you?loginId=8b35f6c8-e7b6-41d3-98f8-08d68b7f8d31&institution=FlinksCapital





















































































 

  1. From the Event Listener

From the Redirect step Object: EXAMPLE:

xxxxxxxxxx
































































































{step: "REDIRECT", institution: "FlinksCapital", url: "https://flinks.io/contact/thank-you?loginId=8b35f6c8-e7b6-41d3-98f8-08d68b7f8d31&institution=FlinksCapital"}





















































































 


Example of Integration


To give you a little push with your test and integration, we have a demo project on Github so you can see what an integration with Flinks Connect would look like: **https://github.com/flinkstech/flinksconnect-integration-demo


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.

xxxxxxxxxx
































































































curl -X POST \
  https://toolbox-api.private.fin.ag/v3/43387ca6-0391-4c82-857d-70d95f087ecb/BankingServices/Authorize \
  -H 'Content-Type: application/json' \
  -d '{
    "LoginId":"a837af05-13bc-41a3-6c07-08d69c41d990",
    "Mostrecentcached":true
}'















































































This endoint will generate you a new RequestId into the response:

xxxxxxxxxx
































































































{
    "Links": [
        {
            "rel": "AccountsDetail",
            "href": "/GetAccountsDetail",
            "example": null
        },
        {
            "rel": "AccountsSummary",
            "href": "/GetAccountsSummary",
            "example": null
        },
        {
            "rel": "Statements",
            "href": "/GetStatements",
            "example": null
        }
    ],
    "HttpStatusCode": 200,
    "Login": {
        "Username": "Greatday",
        "IsScheduledRefresh": false,
        "LastRefresh": "2019-03-04T14:55:29.066305",
        "Type": "Personal",
        "Id": "7ec31114-7a5f-4f1c-3d92-08d6a07eccea"
    },
    "Institution": "FlinksCapital",
    "RequestId": "3f4d3ff9-cda7-45ea-a0f4-95cf7e045a1c"
}














































































 


Step 2: /GetAccountsDetail - Requesting the data

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

xxxxxxxxxx
































































































curl -X POST \
  https://toolbox-api.private.fin.ag/v3/43387ca6-0391-4c82-857d-70d95f087ecb/BankingServices/GetAccountsDetail \
  -H 'Content-Type: application/json' \
  -d '{
    "RequestId": "3f4d3ff9-cda7-45ea-a0f4-95cf7e045a1c"
}'














































































Endpoint call response:

xxxxxxxxxx
































































































{
    "FlinksCode": "OPERATION_PENDING",
    "Links": [
        {
            "rel": "{Endpoint}Async",
            "href": "/{Endpoint}Async",
            "example": "/{Endpoint}Async/{requestId}"
        }
    ],
    "HttpStatusCode": 202,
    "Message": "Your operation is still processing",
    "RequestId": "3f4d3ff9-cda7-45ea-a0f4-95cf7e045a1c"
}














































































 

Important: In case you receive the FlinksCode OPERATION_PENDING, it means that the process dispatched by Flinks Connect is not yet completed.


Step 3 - /GetAccountsDetailAsync - Async polling

At this point, you'll need to make an asynchronous call in a long-polling fashion by calling the async endpoint every 10 seconds, to check if your request is ready:

curl -X GET \
  https://toolbox-api.private.fin.ag/v3/43387ca6-0391-4c82-857d-70d95f087ecb/BankingServices/GetAccountsDetailAsync/3f4d3ff9-cda7-45ea-a0f4-95cf7e045a1c \
  -H 'Content-Type: application/json' 


If the process is still not yet completed, you will continue to receive the Flinks CodeOPERATION_PENDING:

{
    "FlinksCode": "OPERATION_PENDING",
    "Links": [
        {
            "rel": "{Endpoint}Async",
            "href": "/{Endpoint}Async",
            "example": "/{Endpoint}Async/{requestId}"
        }
    ],
    "HttpStatusCode": 202,
    "Message": "Your operation is still processing",
    "RequestId": "3f4d3ff9-cda7-45ea-a0f4-95cf7e045a1c"
}

 


While the /GetAccountsDetailAsync is still pending, repeat this API call every 10 seconds, for a maximum 30 minutes in total:

curl -X GET \
  https://toolbox-api.private.fin.ag/v3/43387ca6-0391-4c82-857d-70d95f087ecb/BankingServices/GetAccountsDetailAsync/3f4d3ff9-cda7-45ea-a0f4-95cf7e045a1c \
  -H 'Content-Type: application/json' 

 

Once ready, the API call will return the code 200 with the corresponding financial data:

{
    "HttpStatusCode": 200,
    "Accounts": [
        {
            "Transactions": [
                {
                    "Date": "2019-02-21",
                    "Code": null,
                    "Description": "Customer Transfer Dr. PC TO 4538220691252",
                    "Debit": 81.24,
                    "Credit": null,
                    "Balance": 484.83,
                    "Id": "8a3ce37d-8798-4aab-b05f-e3cf96e3b5a8"
                },
                {
                    "Date": "2019-02-08",
                    "Code": null,
                    "Description": "Customer Transfer Dr. PC TO 4538220691252",
                    "Debit": 76.18,
                    "Credit": null,
                    "Balance": 566.07,
                    "Id": "6d70ea7a-80d7-4f03-93fa-03cd787e7b85"
                },
                {
                    "Date": "2019-01-30",
                    "Code": null,
                    "Description": "Customer Transfer Dr. PC TO 4538220691252",
                    "Debit": 149.74,
                    "Credit": null,
                    "Balance": 642.25,
                    "Id": "5c1bbfa9-3af6-481e-8473-741ceab83fd6"
                }
            ],
            "TransitNumber": "23481",
            "InstitutionNumber": "002",
            "OverdraftLimit": 0,
            "Title": "Student Banking Advantage Plan",
            "AccountNumber": "0064483",
            "Balance": {
                "Available": null,
                "Current": 484.83,
                "Limit": null
            },
            "Category": "Operations",
            "Type": "Unknown",
            "Currency": "CAD",
            "Holder": {
                "Name": "Alex Lifeson",
                "Address": {
                    "CivicAddress": "240 Somewhere Street",
                    "City": "QUEBEC",
                    "Province": "QUEBEC",
                    "PostalCode": "H4J 2H7",
                    "POBox": null,
                    "Country": "CA"
                },
                "Email": "someone999@gmail.com",
                "PhoneNumber": "(551) 222-2728"
            },
            "Id": "358cb669-7d8d-4dfe-f5cd-08d6a0bb19ba"
        },   
    ],
    "Login": {
        "Username": "453756340066542",
        "IsScheduledRefresh": false,
        "LastRefresh": "2019-03-04T16:14:41.5982464",
        "Type": "Personal",
        "Id": "8b35f6c8-e7b6-41d3-98f8-08d68b7f8d31"
    },
    "Institution": "Scotia",
    "RequestId": "3f4d3ff9-cda7-45ea-a0f4-95cf7e045a1c"
}

 


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 help@flinks.io.