Use an Event Listener - Flinks Documentation

Flinks Connect triggers events based on authentication responses and different steps that the user completes within the application. We recommend adding an Event Listener to your Flinks Connect integration to track your users’ progress and improve their overall experience. As a user progresses through the account connection flow, you’ll be notified of all successful (and unsuccessful) attempts to connect an account. When a user fails to complete the flow successfully, you can review the data from the Event Listener and determine exactly what happened to prevent the same issue from occurring again. For more information about what you can receive from the Event Listener, refer to Reviewing your Event Listener data.

Add the Event Listener to your Integration

To add the Event Listener to your Flinks Connect integration, place the following script on the same page as your Flinks Connect widget:

html

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

Reviewing your Event Listener data

You’ll receive the following types of event data from us:

A JavaScript event, which indicates a user event
A Flinks error code, which indicates an API event

Read the lists below for information on what sorts of event data you can receive for both user and API events. We will notify you of the following user events in Flinks Connect:

EVENT NAME	DESCRIPTION
`APP_MOUNTED`	Flinks Connect has retrieved configuration values from the API, and has successfully loaded.
`APP_ONLINE`	The internet connection was restored to the Flinks Connect application.
`APP_OFFLINE`	The internet connection to the Flinks Connect application was lost.
`APP_RESIZE`	The user has resized the Flinks Connect iframe.
`ACCOUNT_SELECTED`	The user has selected an account to connect.
`COMPONENT_ACCEPT_CONSENT`	The user has provided consent to share their account data.
`COMPONENT_ACCEPT_PROVIDER_CONSENT`	The user has provided consent for their financial institution to share their data.
`COMPONENT_ACCEPT_TERMS`	The user has checked the box to accept the terms and conditions. This is linked in the URL: `termsUrl={https://example.com}`.
`COMPONENT_CLICK_RESET_PASSWORD`	The user has clicked the password reset button.
`COMPONENT_CLICK_TERMS_URL`	The user has clicked on the terms and conditions link.
`COMPONENT_CLOSE_SESSION`	The user has clicked on the close button in the top right corner of the screen. For more information, refer to the `closeEnable` customization parameter.
`COMPONENT_DENY_CONSENT`	The user has denied consent to share their data.
`COMPONENT_DENY_TERMS`	The user unchecked the box on the Terms and Conditions screen, using the `termsUrl` customization parameter.
`COMPONENT_HELP2FA_INFO`	Flinks Connects has either loaded the Help2FA screen, or the user has viewed the troubleshooting screen and has clicked the ‘Back’ button.
`COMPONENT_HELP2FA_TROUBLESHOOTING`	The user has clicked on the troubleshooting tips hyperlink and has viewed the troubleshooting page.
`COMPONENT_LOAD_ACCOUNT_SELECTION`	Flinks Connect has loaded the Account Selection page. This page contains metadata about the user’s accounts (`totalAccounts` and `displayedAccounts`).
`COMPONENT_LOAD_CONSENT`	The consent page has been loaded using the `consentUrl` customization parameter.
`COMPONENT_LOAD_CREDENTIAL`	The user has been asked to enter their username and password for the account with their financial institution.
`COMPONENT_LOAD_CREDENTIAL_RETRY`	The user has received an authorization error and has clicked the ‘Retry’ button.
`COMPONENT_LOAD_INSTITUTION_SELECTOR`	The user has been shown a list of financial institutions to select.
`COMPONENT_LOAD_MFA`	The multi-factor authentication (MFA) page has loaded. This page contains metadata that specifies which MFA challenge the user is presented with (`mfaTypes`).
`COMPONENT_LOAD_MFA_RETRY`	The user has failed the MFA question(s) and has clicked the ‘Retry’ button.
`COMPONENT_PROVIDER_CONSENT_ABOUT`	The user has clicked on the ‘Tell Me More’ hyperlink on the Consent screen.
`COMPONENT_PROVIDER_CONSENT_INFO`	Flinks Connect has loaded the US OAuth consent screen.
`COMPONENT_PROVIDER_CONSENT_LEGAL`	The user has clicked on the ‘Privacy Policy’ hyperlink and has viewed the legal disclaimer.
`COMPONENT_CONSENT_ABOUT_CLOSE`	The user has viewed the Consent Screen in collapsed view.
`COMPONENT_CONSENT_ABOUT_OPEN`	The user has viewed the Consent Screen in expanded view.
`COMPONENT_CONSENT_INTRO`	The user has viewed the Consent Screen with the `consentTitleAppendText` parameter enabled.
`COMPONENT_CONSENT_PRIVACY`	The user has viewed the Flinks Privacy Statement page.
`COMPONENT_CONSENT_PRIVACY_OPEN`	The user has clicked the ‘Flinks Services Privacy Statement’ hyperlink.
`COMPONENT_CONSENT_PRIVACY_CLOSE`	The user has clicked the close button on the privacy statement page.
`COMPONENT_BACK_SESSION`	The `backEnable` customization parameter is enabled.
`COMPONENT_LOAD_UPLOAD`	The user has selected the Flinks Upload screen.
`UPLOAD_INPUT_CHANGE`	The user has uploaded a file.
`UPLOAD_SUBMIT`	The user has submitted their file to us.
`DISABLED_INSTITUTION`	An institution is disabled.
`ENHANCED_MFA_HAS_QUESTIONS`	There was one or more unanswered MFA questions (when the `enhancedMFA=true` customization parameter is enabled).
`ENHANCED_MFA_NO_QUESTIONS`	There were no unanswered MFA questions (when the `enhancedMFA=true` customization parameter is enabled).
`ENHANCED_MFA_SUCCESS`	The user has successfully completed the MFA flow (when the `enhancedMFA=true` customization parameter is enabled).
`INSTITUTION_SELECTED`	The user has selected their financial institution.
`INVALID_INSTITUTION`	A financial institution is invalid.
`INSTITUTION_NOT_AVAILABLE`	A financial institution is not available.
`INVALID_SECURITY_RESPONSE`	The user has failed the MFA challenge.
`MAXIMUM_RETRY_REACHED`	The user has reached the maximum number of retries permitted (when the `maximumRetry={number}` customization parameter is enabled).
`QUESTION_NOT_FOUND`	The MFA challenge is returned by the API. This page contains metadata that specifies which MFA challenge the user is presented with (`mfaTypes`).
`REDIRECT`	The user has successfully completed the account connection flow and are redirected.
`RESUME_SELECTED_ACCOUNTS_INVALID`	One or more account IDs passed in `resumeSelectedAccounts` were rejected by the backend. Payload includes the attempted `accountId`(s) and the `flinksCode` returned.
`RETRY_COUNT`	The user has failed the authorization process and the number of retries are recorded, starting from 0.
`SESSION_NONEXISTENT or SESSION_EXPIRED`	The session has expired.
`SESSION_STORAGE_BLOCKED`	Legacy cookie management (deprecated).
`SESSION_STORAGE_BLOCKED_RETRY`	Legacy cookie management (deprecated).
`SKIP_ENHANCED_MFA`	The user has skipped the unanswered MFA questions (when the `enhancedMFA=true` customization parameter is enabled).
`SUBMIT_ANSWER_MFA_QUESTIONS`	The user has submitted the unanswered MFA questions.
`SUBMIT_CREDENTIAL`	The form is valid and the user clicks the ‘Continue’ button.
`SUBMIT_GET_MFA_QUESTIONS`	We’ve received unanswered MFA questions (when the `enhancedMFA=true` customization parameter is enabled).
`SUBMIT_MFA`	The user has submitted the MFA questions.
`TOKEN_INVALID`	The authorize token has expired. Generate a new token and reload the iframe. See Handle token expiry.
`BACK_SECTION`	The user has clicked on the ‘Back’ button (when the `backEnable` customization parameter is enabled).
`FEEDBACK`	The user has opted to provide feedback about their connection experience.
`POPUP_BLOCKED`	The OAuth connection was blocked.
`POPUP_CLOSED`	The OAuth connection was closed.
`POPUP_OPENED`	The OAuth connection was initiated.
`POPUP_UPDATED`	The OAuth connection has been updated.

Additionally, we will notify you of the following API events in Flinks Connect.

HTTP STATUS CODE	FLINKS CODE	DESCRIPTION	MESSAGE	STEPS TO REPRODUCE
200	`N/A`	The connection was successful.	Complete a successful request.	Complete a successful request.
202	`OPERATION_PENDING`	The process is ongoing in the background. At this point, your flow much change to the async endpoint.	Your operation is still processing.	Perform a cached flow immediately after Authorizing a new account.
202	`OPERATION_DISPATCHED`	Your sync request took more than 210 seconds and it was dispatched in the background.	Your operations had been dispatched to background process for long running jobs.	Have a live request to gather /GetAccountDetails in more than 210 seconds.
400	`SESSION_NONEXISTENT`	A request was made with an expired `requestId`.	Inputs session id or card if were not found.	Use an old `requestId` for a new request.
400	`CARD_IN_USE`	An operation was requested while the account is still being processed.	Call the /DeleteCard endpoint immediately after Authorizing a new account.	Call the /DeleteCard endpoint immediately after Authorizing a new account.
401	`ACCESS_DENIED`	Authentication was unsuccessful.
401	`INVALID_LOGIN`	The provided `loginId` is invalid.	The `loginId` provided is either invalid or does not belong to the customerId.	Call the /Authorize endpoint using a non existent `loginId`.
401	`INVALID_LOGIN`	The provided username or/and password is/are invalid.	The card number (username) or password provided is invalid.	Call the /Authorize endpoint using non valid credentials.
401	`INVALID_REQUEST`	Credentials are missing/incomplete, or syntax is incorrect (e.g. missing comma).	Message returned will depend on the error (e.g. missing value, incorrect syntax, etc.).	In input, make a typo, remove a comma, etc.
401	`INVALID_SECURITY_RESPONSE_NO_RETRY`	The user has provided incorrect or incomplete MFA answers and cannot retry.
401	`INVALID_USERNAME`	The username provided was different from what the bank expected.		Provide an invalid username to an Authorize request.
401	`INVALID_PASSWORD`	The password provided was different from what the bank expected.		Provide an invalid password to an Authorize request.
401	`INVALID_SECURITY_RESPONSE`	The MFA response provided was different from what the bank expected.		Provide an invalid MFA answer to an Authorize request.
401	`QUESTION_NOT_FOUND`	The MFA prompt doesn’t have a stored answer.
401	`RETRY_LATER`	Flinks was not able to open a connection with the selected financial institution.
401	`T00_MANY_REQUESTS`	The endpoint has received too many requests in a given amount of time.
401	`UNKNOWN_CHALLENGE_KEY`	The `/Authorize` request to respond an MFA contain an answer to the wrong MFA prompt.	”One or more of the Security Challenge Prompts required are missing in the provided response.”	Change the MFA prompted, or leave the MFA prompt blank in the input Change the MFA response or leave the MFA response blank.
401	`CONCURRENT_SESSION`	Another session is already opened with this `loginId`.		Open two requests simultaneously with the same account.
401	`UNAUTHORIZED`	The card was not authorized. Either there is a problem with bank, or the `/GetAccountsDetail` endpoint was called before authorized.	You need to be authorized in the bank account before going further.	Call the `/GetAccountsDetail` endpoint during an MFA prompt without answering the MFA question.
401	`UNHANDLED`	An error was encountered that cannot be handled or processed.
401	`DISABLED_LOGIN`	The account has been deactivated by the financial institution. The account holder must contact their bank.		Log into a deactivated account.
401	`NEW_ACCOUNT`	The end user must take action directly on their online banking before connecting an account with Flinks.		Login to an account where the user must take action on the bank’s website (e.g. to accept a consent form).
401	`SESSION_EXPIRED`	The `requestId` expired after 8 mins of inactivity, during Authorize, or during 30 mins timeout for data processing.		Wait at least 8 minutes before responding to MFA.
401	`ALREADY_AUTHORIZED`	When the `/Authorize` endpoint is called after the user has already been authorized.	Answer an MFA for an already authorized `requestId`.	Answer an MFA for an already authorized `requestId`.
401	`SECURITYRESPONSES_INCOMPLETE`	Not all the prompted MFA questions had answers in the response request.	Not answer all MFA questions prompted in 3 question MFA prompt.	Not answer all MFA questions prompted in 3 question MFA prompt.
404	`NO_TRANSACTION`	The account does not have any transactions.	No transactions were found.	Perform an Attributes request for an account with no `/GetAccountDetails` previously processed.
405	`DISABLED_INSTITUTION`	The selected financial institution is not available.
500	`AGGREGATION_ERROR`	Flinks had an unexpected error and could not process your request.
501	`METHOD_NOT_AVAILABLE`	The requested API is not currently enabled in your instance. Kindly contact us if you wish to use this feature.

For information about how Flinks Connect handles common errors and their corresponding events, see Handled Errors.

Examples

A successful connection journey

In a typical successful connection, the events fire in roughly this order. Listening for them lets you track where each user is in the flow and measure drop-off between steps:

Order	Event	What just happened
1	`APP_MOUNTED`	Flinks Connect loaded
2	`COMPONENT_LOAD_INSTITUTION_SELECTOR`	The institution list was shown
3	`INSTITUTION_SELECTED`	The user picked their financial institution
4	`COMPONENT_LOAD_CREDENTIAL`	The user was asked for their credentials
5	`COMPONENT_LOAD_MFA`	An MFA challenge was presented (if required)
6	`COMPONENT_ACCEPT_CONSENT`	The user consented to share their data
7	`ACCOUNT_SELECTED`	The user selected an account (if `accountSelectorEnable=true`)
8	`REDIRECT`	The connection succeeded and the `loginId` is available

The final REDIRECT event is where you capture the loginId (and accountId) to continue on the back end:

Json

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

Diagnosing a missing-credentials issue

When a user can’t get past the credentials step, the event stream tells you why. A loop of COMPONENT_LOAD_CREDENTIAL → error → COMPONENT_LOAD_CREDENTIAL_RETRY points to invalid credentials, while the MFA equivalents point to failed challenges. Correlate the event with the API event returned at the same time:

Event observed	Likely API code	Meaning
`COMPONENT_LOAD_CREDENTIAL_RETRY`	`INVALID_USERNAME` / `INVALID_PASSWORD`	The username or password did not match what the bank expected
`COMPONENT_LOAD_MFA_RETRY` / `INVALID_SECURITY_RESPONSE`	`INVALID_SECURITY_RESPONSE`	The MFA answer was incorrect
`MAXIMUM_RETRY_REACHED`	n/a	The user exhausted the allowed retries (`maximumRetry`)
`SESSION_NONEXISTENT or SESSION_EXPIRED`	`SESSION_EXPIRED`	The `requestId` expired (8 minutes of inactivity)

Use these signals to show the user a targeted message (for example, “Double-check your username” on repeated COMPONENT_LOAD_CREDENTIAL_RETRY) instead of a generic error.

​Add the Event Listener to your Integration

​Reviewing your Event Listener data

​Examples

​A successful connection journey

​Diagnosing a missing-credentials issue

Add the Event Listener to your Integration

Reviewing your Event Listener data

Examples

A successful connection journey

Diagnosing a missing-credentials issue