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.
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:
- Reset Questions/Answers when questions are provided.
- 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"
}
]
}
Triple MFA 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.
A SecurityChallenges object 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:
- Login credentials (username + password)
- 1st MFA (security question)
- 2nd MFA (image selection)
For example, a security challenge object will be presented as such: Type ImageSelection with a Prompt and a list of Iterables 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:
- Login credentials (username + password)
- 1st MFA (SecurID code)
- 2nd MFA (regular security question)
{
"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, and MultipleChoiceMultipleAnswers wherein MultipleChoice responses expect only one answer, and the MultipleChoiceMultipleAnswers expect one or more answers.
The procedure would be as follows:
-
Login credentials (username + password)
-
1st set of Security Challenges : Personal Multiple Choice Questions
-
2nd set of Security Challenges : Choosing a set of new Security Questions
Step 1:
Login credentials
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"
]
}
}'
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"
]
}
]
}
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" ]
}
}'
Step 3:
Choosing a set of new Security Questions:
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:
Step 1:
After your regular first Authorize call, the API will prompt the 2 Step Verification Security Code in the API response.
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
}'
API Response:
{ ...
"RequestId" : "2b000833-0bf4-4705-9ef8-80d4572af4c4",
"SecurityChallenges": [
{
"Type" : "TextOrCall",
"Prompt" : "Choose a phone number",
"Iterables" : [
"PhoneNumber #1",
"PhoneNumber #2",
"PhoneNumber #3",
...
]
}
]
}
Step 2: Selecting a phone number and how to be contacted
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.
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" ]
}
}'
API Response:
{ ...
"RequestId" : "2b000833-0bf4-4705-9ef8-80d4572af4c4",
"SecurityChallenges" : [
{
"Type" : "QuestionAndAnswer",
"Prompt" : "Enter the security code"
}
]
}
Step 3: Entering the security code
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" ]
}
}'
Once TD validates the sent security code, you will receive a 200 response from the API.
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:
Step 1
After your regular first Authorize call, the API will prompt the 2-Step Verification Notification in the API response.
curl 'https://toolbox.flinks.com/v3/{CustomerId}/BankingServices/Authorize' \
-H 'content-type: application/json' \
-d '{
"LoginId": "{LoginId}",
"MostRecentCached": false,
"Save": true
}'
API Response:
{
"SecurityChallenges": [
{
"Type": "WaitUntilEUAccept",
"Prompt": "Please verify your identity on your trusted device"
}
]
}
Step 2
Informing Flinks that the consent was given through the trusted device, answering the MFA via /Authorize:
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"
]
}
}'
Once validated by the financial institution, a 200 response will be given by Flinks API:
{
"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}"
}