Changelog
< Back to Flinks

Legacy API Integrations

Suggest Edits

🚧

Disclaimer

Please be mindful that this session addresses a legacy type of integration with Flinks. The following articles are mostly to support customers that are already live with this methodology.

Flinks Connect was developed to replace this integration and solve the following challenges:

  • Increase conversion rate.
  • Avoid maintenance efforts on your side to account for authentication flow changes by the financial institution.
  • It includes support for our new OAuth connections which is not the case with the legacy flow.

/Authorize

ℹ️

This is only required for legacy integrations

This is only required if you are using a legacy integration (that does not support OAuth 2.0). If you are using a custom integration that supports OAuth 2.0, see Using a Custom API Integration.

Generating a new requestId

All retrieval of data starts with new session being initiated. For that, you need to generate a new requestId with Flinks by calling /Authorize.

For custom integrations, all credentials handling between Flinks and the Financial Institution is controlled by /Authorize in live mode (when using MostRecentCached:false), and any Multi-Factor Authentication (MFA) prompts needs to also be handled.

ℹ️

Integrating with Flinks Connect?

Integrations that uses Flinks Connect for handling user banking authentication, uses /Authorize in cached mode, by only specifying the parameter "MostRecentCached": "true" and LoginId, as you need to retrieve already processed data. More details can be found here.

When handling a custom integration, a typical /Authorize initial request body would look like this:

{
    "Institution":"FlinksCapital",
    "username": "Greatday",
    "Password": "Everyday",
    "MostRecentCached":false,
    "Save": true
}

Multi-Factor Authentication

Most financial institutions implement Multi-Factor Authentication, which can be prompted after the first credential pair (username and password) is submitted via /Authorize.

Here is an example of a simple MFA prompt response:

{
    "Links": [
        {
            "rel": "Authorization",
            "href": "/Authorize",
            "example": null
        }
    ],
    "HttpStatusCode": 203,
    "SecurityChallenges": [
        {
            "Type": "QuestionAndAnswer",
            "Prompt": "What shape do people like most?"
        }
    ],
    "Institution": "FlinksCapital",
    "RequestId": "9022abc2-8a2e-4b06-a06e-c3e5449c4d10"
}

In order to complete the session opening, the MFA prompt needs to be answered by calling /Authorize, using the new RequestId (session reference), contained in this first response.

Here is the example of the MFA answer request:

{
    "RequestId": "006fd2f3-055b-4ef6-a9fc-c1261cd76ec6",
    "SecurityResponses": {
        "What shape do people like most?": [
            "Triangle"
        ]
    }
}

When Flinks validates with the financial institution that all submitted credentials are valid and no additional information is required, /Authorize will respond with a 200 HTTP status code.

{
    "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": "2020-04-15T22:46:03.1690585",
        "Type": "Personal",
        "Id": "b0debb48-f9f1-46c6-80a4-08d7dd88d478"
    },
    "Institution": "FlinksCapital",
    "RequestId": "006fd2f3-055b-4ef6-a9fc-c1261cd76ec6"
}

Once this step is reached, it means that your session was successfully opened, and the received RequestId can be used to make calls to other data retrieval endpoints. (/GetAccountDetails, for example).

LoginId

All successfully completed /Authorize step will also return you a LoginId. (which in the last example was b0debb48-f9f1-46c6-80a4-08d7dd88d478)

A LoginId is the reference of the saved connected account, which needs to be kept safe. If in a later moment you would like simply to retrieve the saved data on a particular account, its LoginId needs to be used on a cached call flow. (In a similar way as Flinks Connect integrations retrieve data).

🚧

Keep track of each new LoginId, for a later use, or even for a later deletion of data, since Flinks will retain data indefinitely unless /DeleteCard is used.

MFA Types

ℹ️

This is only required for legacy integrations

This is only required if you are using a legacy integration (that does not support OAuth 2.0). If you are using a custom integration that supports OAuth 2.0, see Using a Custom API Integration.

Special Authorize Flows

Financial institutions can vary on the format of their Multi-Factor Authentication. In this section we have all types of MFA you need to handle in case of a custom integration, including:

  • Triple MFA
  • Image selection
  • SecurID
  • Reset security questions
  • Two-step verification security code
  • Trusted device verification

ℹ️

Flinks Connect

Flinks Connect widget already did all the work for you. Most of the time we recommend integrations with our widget. More details here

Case 1 (RBC): Triple MFA

This special case is often presented after an incorrect answer is provided in a previous attempt. When this process is triggered, RBC present one of the following procedures:

  1. Reset Questions/Answers when questions are provided.
  2. Reset Questions/Answers when user has to select new questions.

Case 1: Reset Questions/Answers when the questions are provided.

A triple MFA is presented at once: instead of having to give one answer to a single question, the user needs to give an answer to three different questions. It’s important that you return all three answers in the same call.

Prompt example: 

{ ...
  "RequestId"           : "2b000833-0bf4-4705-9ef8-80d4572af4c4",
  "SecurityChallenges"  : [
    {
      Type              : "QuestionAndAnswer",
      Prompt            : "What is the name of your mother"
    },
    {
      Type              : "QuestionAndAnswer",
      Prompt            : "What is the name of your father"
    },
    {
      Type              : "QuestionAndAnswer",
      Prompt            : "What is the name of your dog"
    }
  ]
}

Response example: 

curl 'https://sandbox.flinks.com/v3/{CustomerId}/BankingServices/Authorize' \
  -H 'content-type: application/json' \
  -d '{
        "RequestId"         : "2b000833-0bf4-4705-9ef8-80d4572af4c4",
        "SecurityResponses" : {
              "What is the name of your mother" : [ "Louise" ],
              "What is the name of your father" : [ "Paul" ],
              "What is the name of your dog"    : [ "Wouf" ]
        }
      }'

Case 2 (RBC): Select New Questions and Answers

Now the user has to select three new questions on top of providing three answers. When this case is prompted, we’ll send you three lists of questions; from each list, your user has to choose one question, and then provide an answer.

Example: SecurityChallenges object that will be returned

{ ...
  "RequestId"           : "2b000833-0bf4-4705-9ef8-80d4572af4c4",
  "SecurityChallenges"  : [
    {
      Type              : "QuestionAndAnswer",
      Prompt            : "Personal Verification Question 1",
      Iterables         : [
        "What is the name of my mother",
        "What is the name of my dog",
        "..."
      ]
    },
    {
      Type              : "QuestionAndAnswer",
      Prompt            : "Personal Verification Question 2",
      Iterables: [
        "What is the name of my mother",
        "What is the name of my dog",
        "..."
      ]
    },  
    {
      Type              : "QuestionAndAnswer",
      Prompt            : "Personal Verification Question 3",
      Iterables: [
        "What is the name of my mother",
        "What is the name of my dog",
        "..."
      ]
    }
  ]
}

Case 3 (Laurentienne): Image selection MFA

The authentication process with Laurentienne Bank presents the user with an additional security challenge in the form of an image selection from a list of 16 different images. The Authorize flow looks like this:

  1. Login credentials (username + password)
  2. 1st MFA (security question)
  3. 2nd MFA (image selection)

Example: SecurityChallenges object that will be presented as such and comprised of strings in base64 encoding 

"SecurityChallenges": [
  {
    "Type"      : "ImageSelection",
    "Prompt"    : "Select an image",
    "Iterables" : [
        "base64ImageString1",
        "base64ImageString2",
        ...
    ]
  }
]

🚧

Base64 encoded image string

The image strings within the list of Iterables might be have around 4,000 characters of length each.

Case 4 (National): SecurID MFA

Some National Bank accounts have SecurID MFA enabled, which needs to be answered in a 2 step verification process. The SecurId code will always have 6 digits and needs to be properly answered when it's prompted. As it's an extra step in the Authorize process, here's the order of prompts:

  1. Login credentials (username + password)
  2. 1st MFA (SecurID code)
  3. 2nd MFA (regular security question)

Example: 

{
    "SecurityChallenges": [
      {
        "Type"   : "QuestionAndAnswer",
        "Prompt" : "Enter your SecurID"
      }
    ]
  }

ℹ️

Nightly Refreshes

Accounts with 2step verification are not able to automatic refreshes.

Case 5 (Scotia): Reset Security Questions

With Scotia, a user may be prompted to reset their security questions.

The user may be presented with a set of multiple choice questions. There are two distinct types:

  • MultipleChoice: Expects only one answer
  • MultipleChoiceMultipleAnswers: Expects one or more answers

The procedure is as follows:

  1. Login credentials (username and password)
  2. First set of Security Challenges (personal multiple choice questions)
  3. Second set of Security Challenges (choosing a set of new security questions)

Example: Step 2 Response

curl 'https://sandbox.flinks.com/v3/{CustomerId}/BankingServices/Authorize' \
  -H 'content-type: application/json' \
  -d '{
        "RequestId"         : "2b000833-0bf4-4705-9ef8-80d4572af4c4",
        "SecurityResponses" : {
          "Choose one of the following:" : [
            "None of the above"
          ]
          "What purchases did you make over the last 10 days?" : [ 
            "Purchase 1: $10.35", 
            "Purchase 3: $143.86" 
          ]
        }
      }'

Example: Step 2 Personal Multiple Choice Questions

{ ...
  "RequestId"           : "2b000833-0bf4-4705-9ef8-80d4572af4c4",
  "SecurityChallenges": [
    {
      "Type"   : "MultipleChoice",
      "Prompt" : "Choose one of the following:",
      "Iterables" : [
        "Something",
        "Something else",
        "...",
        "None of the above"
      ]
    },
    {
      "Type"   : "MultipleChoiceMultipleAnswers",
      "Prompt" : "What purchases did you make over the last 10 days?",
      "Iterables" : [
        "Purchase 1: $10.35",
        "Purchase 2: $73.42",
        "Purchase 3: $143.86",
        "...",
        "None of the above"
      ]
    }
  ]
}

Example: Step 3 Response

curl 'https://sandbox.flinks.com/v3/{CustomerId}/BankingServices/Authorize' \
  -H 'content-type: application/json' \
  -d '{
        "RequestId"         : "2b000833-0bf4-4705-9ef8-80d4572af4c4",
        "SecurityResponses" : {
          "What is the name of your mother" : [ "Louise" ],
          "What is the name of your father" : [ "Paul" ],
          "What is the name of your dog"    : [ "Wouf" ]
        }
      }'

Example: Step 3 Choosing a set of new Security Questions

ℹ️

Note:

This is identical to the procedure as described above with Case 2: Reset Questions/Answers when user has to select new questions.

{ ...
  "RequestId"           : "2b000833-0bf4-4705-9ef8-80d4572af4c4",
  "SecurityChallenges"  : [
    {
      Type              : "QuestionAndAnswer",
      Prompt            : "Personal Verification Question 1",
      Iterables         : [
        "What is the name of my mother",
        "What is the name of my dog",
        "..."
      ]
    },
    {
      Type              : "QuestionAndAnswer",
      Prompt            : "Personal Verification Question 2",
      Iterables: [
        "What is the name of my mother",
        "What is the name of my dog",
        "..."
      ]
    },  
    {
      Type              : "QuestionAndAnswer",
      Prompt            : "Personal Verification Question 3",
      Iterables: [
        "What is the name of my mother",
        "What is the name of my dog",
        "..."
      ]
    }
  ]
}

Case 6 (TD): 2 Step Verification Security Code

TD users may be prompted to enter a security code sent to their phone via a text message or phone call. The API will present a SecurityChallenge of type TextOrCall. The procedure is as follows:

  1. After your regular first Authorize call, the API will prompt the 2 Step Verification Security Code in the API response.
  2. In the next Authorize call, you have to pass the registered telephone number and the method of receiving the security code. There are two means by which a user can be contacted: Text or Call. After that, the end-user will receive the code from the chosen method and phone number, which will be used for the next step.
  3. Enter the security code. Once TD validates the sent security code, you will receive a 200 response from the API.

Example: Step 1 Regular first Authorize call

curl 'https://sandbox.flinks.com/v3/{CustomerId}/BankingServices/Authorize' \
  -H 'content-type: application/json' \
  -d '{
        "Institution" : "TD",
        "Username"    : "{username}",
        "Password"    : "{password}",
        "save"      : true
    }'

Example: Step 1 API Response

{ ...
  "RequestId"           : "2b000833-0bf4-4705-9ef8-80d4572af4c4",
  "SecurityChallenges": [
    {
      "Type"   : "TextOrCall",
      "Prompt" : "Choose a phone number",
      "Iterables" : [
        "PhoneNumber #1",
        "PhoneNumber #2",
        "PhoneNumber #3",
        ...
      ]
    }
  ]
}

Example: Step 2 Request

curl 'https://sandbox.flinks.com/v3/{CustomerId}/BankingServices/Authorize' \
  -H 'content-type: application/json' \
  -d '{
        "RequestId"         : "2b000833-0bf4-4705-9ef8-80d4572af4c4",
        "SecurityResponses" : {
          "PhoneNumber #2" : [ "Text" ]
       }
    }'

Example: Step 2 API Response

{ ...
  "RequestId"           : "2b000833-0bf4-4705-9ef8-80d4572af4c4",
  "SecurityChallenges"  : [
    {
      "Type"              : "QuestionAndAnswer",
      "Prompt"            : "Enter the security code"
    }
  ]
}

Example: Step 3 Requests

curl 'https://sandbox.flinks.com/v3/{CustomerId}/BankingServices/Authorize' \
  -H 'content-type: application/json' \
  -d '{
        "RequestId"         : "2b000833-0bf4-4705-9ef8-80d4572af4c4",
        "SecurityResponses" : {
          "Enter the security code" : [ "123456" ]
        }
      }'

Example: Step 3 API Response

{
    "Links": [
        {
            "rel": "AccountsDetail",
            "href": "/GetAccountsDetail",
            "example": null
        },
        {
            "rel": "AccountsSummary",
            "href": "/GetAccountsSummary",
            "example": null
        },
        {
            "rel": "Statements",
            "href": "/GetStatements",
            "example": null
        }
    ],
    "HttpStatusCode": 200,
    "Login": {
        "Username": "{username}",
        "IsScheduledRefresh": false,
        "LastRefresh": "2018-05-23T15:10:51.65608",
        "Id": "f51a811f-6e01-a901-bf33-352abf17bbe1"
    },
    "Institution": "TD",
    "RequestId": "2b000833-0bf4-4705-9ef8-80d4572af4c4"
}

Case 7 (RBC): Trusted device verification

In this MFA flow, a trusted user’s device receives a notification to confirm the authentication.The API presents a SecurityChallenge of type WaitUntilEUAccept. The procedure is as follows:

  1. After your regular first Authorize call, the API will prompt the 2-Step Verification Notification in the API response.
  2. Inform Flinks that the consent was given through the trusted device by answering the MFA via /Authorize. Once validated by the financial institution, a 200 response will be given by Flinks API.

Example: Step 1 API call

curl 'https://toolbox.flinks.com/v3/{CustomerId}/BankingServices/Authorize' \
  -H 'content-type: application/json' \
  -d '{
        "LoginId": "{LoginId}",
        "MostRecentCached": false,
        "Save": true
    }'

Example: Step 1 API Response

{
    "SecurityChallenges": [
      {
        "Type": "WaitUntilEUAccept",
        "Prompt": "Please verify your identity on your trusted device"
      }
    ]
}

Example: Step 2 API call

curl 'https://toolbox.flinks.com/v3/{CustomerId}/BankingServices/Authorize' \
  -H 'content-type: application/json' \
  -d '{
    "RequestId": "{RequestId}",
    "SecurityResponses": {
        "Please verify your identity on your trusted device": [
            "VERIFIED"
        ]
    }
}'

Example: Step 2 Response

{
    "Links": [
        {
            "rel": "AccountsDetail",
            "href": "/GetAccountsDetail",
            "example": null
        },
        {
            "rel": "AccountsSummary",
            "href": "/GetAccountsSummary",
            "example": null
        },
        {
            "rel": "Statements",
            "href": "/GetStatements",
            "example": null
        }
    ],
    "HttpStatusCode": 200,
    "Login": {
        "Username": "{username}",
        "IsScheduledRefresh": false,
        "LastRefresh": "2018-05-23T15:10:51.65608",
        "Id": "f51a811f-6e01-a901-bf33-352abf17bbe1"
    },  
    "Institution": "RBC",
    "RequestId": "{RequestId}"
}

Updated 4 months ago