> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flinks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Legacy API Integrations
> Reference guide for legacy API integrations using /Authorize, replaced by Flinks Connect.
Disclaimer
Please be mindful that this session addresses a legacy type of integration with Flinks. The following articles are mostly to support customers who 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 Custom Integrations.
### Generating a new requestId
All retrieval of data starts with a 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 need to also be handled.
Integrating with Flinks Connect?
Integrations that use Flinks Connect for handling user banking authentication, use `/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:
```json Json theme={null}
{
"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:
```json Json theme={null}
{
"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 an example of the MFA answer request:
```json Json theme={null}
{
"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.
```json Json theme={null}
{
"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.**
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.
### Special Authorize Flows
Financial institutions can vary in 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
If you're using Flinks Connect, it will do all of this work for you.
#### 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:**
```json Json theme={null}
{ ...
"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:**
```json Json theme={null}
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.
```json Json theme={null}
{ ...
"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.
```json Json theme={null}
"SecurityChallenges": [
{
"Type" : "ImageSelection",
"Prompt" : "Select an image",
"Iterables" : [
"base64ImageString1",
"base64ImageString2",
...
]
}
]
```
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 need 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:**
```json Json theme={null}
{
"SecurityChallenges": [
{
"Type": "QuestionAndAnswer",
"Prompt": "Enter your SecurID"
}
]
}
```
**Accounts with 2 step 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 curl theme={null}
curl 'https://sandbox.flinks.com/v3/43387ca6-0391-4c82-857d-70d95f087ecb/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
```json Json theme={null}
{ ...
"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 curl theme={null}
curl 'https://sandbox.flinks.com/v3/43387ca6-0391-4c82-857d-70d95f087ecb/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.**
```json Json theme={null}
{
"...""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 curl theme={null}
curl 'https://sandbox.flinks.com/v3/43387ca6-0391-4c82-857d-70d95f087ecb/BankingServices/Authorize' \
-H 'content-type: application/json' \
-d '{
"Institution" : "TD",
"Username" : "{username}",
"Password" : "{password}",
"save" : true
}'
```
**Example:** Step 1 API Response
```json Json theme={null}
{ ...
"RequestId" : "2b000833-0bf4-4705-9ef8-80d4572af4c4",
"SecurityChallenges": [
{
"Type" : "TextOrCall",
"Prompt" : "Choose a phone number",
"Iterables" : [
"PhoneNumber #1",
"PhoneNumber #2",
"PhoneNumber #3",
...
]
}
]
}
```
**Example:** Step 2 API Response
```json Json theme={null}
{ ...
"RequestId" : "2b000833-0bf4-4705-9ef8-80d4572af4c4",
"SecurityChallenges" : [
{
"Type" : "QuestionAndAnswer",
"Prompt" : "Enter the security code"
}
]
}
```
**Example:** Step 3 Requests
```curl curl theme={null}
curl 'https://sandbox.flinks.com/v3/43387ca6-0391-4c82-857d-70d95f087ecb/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
```json Json theme={null}
{
"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: 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 curl theme={null}
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
```json Json theme={null}
{
"SecurityChallenges": [
{
"Type": "WaitUntilEUAccept",
"Prompt": "Please verify your identity on your trusted device"
}
]
}
```
**Example:** Step 2a) API call
```curl curl theme={null}
curl 'https://toolbox.flinks.com/v3/43387ca6-0391-4c82-857d-70d95f087ecb/BankingServices/Authorize' \
-H 'content-type: application/json' \
-d '{
"RequestId": "{RequestId}",
"SecurityResponses": {
"Please verify your identity on your trusted device": [ "VERIFIED" ]
}
}'
```
**Example:** Step 2a) Response
```json Json theme={null}
{
"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}"
}
```
**Example:** Step 2b) If no push notification is received, send a second API call:
```json Json theme={null}
{
"RequestId": "{{requestId}}",
"SecurityResponses": { "{{prompt}}": ["NOT_RECEIVED"] }
}
```
**Example:** Step 2b) Response
```json Json theme={null}
{
"HttpStatusCode": 401,
"FlinksCode": "CHALLENGE_NOT_RECEIVED",
"Message": "User did not receive response from the bank"
}
```