Set Up an Event Listener

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 into your Flinks Connect integration, place the following script on the same page as your Flinks Connect widget:

<!-- 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

For more information about the errors you may receive, see List of user events and List of API events.

List of user events

We will notify you of the following events in Flinks Connect:

Event NameDescription
APP_MOUNTEDFlinks Connect has retrieved configuration values from the API, and has successfully loaded.
APP_ONLINEThe internet connection was restored to the Flinks Connect application.
APP_OFFLINEThe internet connection to the Flinks Connect application was lost.
ACCOUNT_SELECTEDThe user has selected an account to connect.
COMPONENT_ACCEPT_CONSENTThe user has provided consent to share their account data.
COMPONENT_ACCEPT_PROVIDER_CONSENTThe user has provided consent for their financial institution to share their data.
COMPONENT_ACCEPT_TERMSThe user has checked the box to accept the terms and conditions. This is linked in the URL: termsUrl={https://example.com}.
COMPONENT_CLICK_RESET_PASSWORDThe user has clicked the password reset button.
COMPONENT_CLICK_TERMS_URLThe user has clicked on the terms and conditions link.
COMPONENT_CLOSE_SESSIONThe 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_CONSENTThe user has denied consent to share their data.
COMPONENT_DENY_TERMSThe user unchecked the box on the Terms and Conditions screen, using the termsUrl customization parameter.
COMPONENT_HELP2FA_INFOFlinks Connects has either loaded the Help2FA screen, or the user has viewed the troubleshooting screen and has clicked the 'Back' button
to return.
COMPONENT_HELP2FA_TROUBLESHOOTINGThe user has clicked on the troubleshooting tips hyperlink and has viewed the troubleshouting page.
COMPONENT_LOAD_ACCOUNT_SELECTIONFlinks Connect has loaded the Account Selection page. This page contains metadata about the user's accounts (totalAccounts and displayedAccounts).
COMPONENT_LOAD_CONSENTThe consent page has been loaded using the consentEnable=true customization parameter.
COMPONENT_LOAD_CREDENTIALThe user has been asked to enter their username and password for the account with their financial institution.
COMPONENT_LOAD_CREDENTIAL_RETRYThe user has received an authorization error and has clicked the 'Retry' button.
COMPONENT_LOAD_INSTITUTION_SELECTORThe user has been shown a list of financial institutions to select.
COMPONENT_LOAD_MFAThe 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_RETRYThe user has failed the MFA question(s) and has clicked the 'Retry' button.
COMPONENT_PROVIDER_CONSENT_ABOUTThe user has clicked on the 'Tell Me More' hyperlink on the Consent screen.
COMPONENT_PROVIDER_CONSENT_INFOFlinks Connect has loaded the US OAuth consent screen.
COMPONENT_PROVIDER_CONSENT_LEGALThe user has clicked on the 'Privacy Policy' hyperlink and has viewed the legal disclaimer.
COMPONENT_CONSENT_ABOUT_CLOSEThe user has viewed the Consent Screen in collapsed view.
COMPONENT_CONSENT_ABOUT_OPENThe user has viewed the Consent Screen in expanded view.
COMPONENT_CONSENT_INTROThe user has viewed the Consent Screen with the consentTitleAppendText parameter enabled.
COMPONENT_CONSENT_PRIVACYThe user has viewed the Flinks Privacy Statement page.
COMPONENT_CONSENT_PRIVACY_OPENThe user has clicked the 'Flinks Services Privacy Statement` hyperlink.
COMPONENT_CONSENT_PRIVACY_CLOSEThe user has clicked the close button on the privacy statement page.
COMPONENT_BACK_SESSIONThe [backEnable](https://docs.flinks.com/docs/customize-your-integration#layout-customization) customization parameter is enabled.
COMPONENT_LOAD_UPLOADThe user has selected the Flinks Upload screen.
UPLOAD_INPUT_CHANGEThe user has uploaded a file.
UPLOAD_SUBMITThe user has submitted their file to us.
DISABLED_INSTITUTIONAn institution is disabled.
ENHANCED_MFA_HAS_QUESTIONSThere was one or more unanswered MFA questions (when the enhancedMFA=true customization parameter is enabled).
ENHANCED_MFA_NO_QUESTIONSThere were no unanswered MFA questions (when the enhancedMFA=true customization parameter is enabled).
ENHANCED_MFA_SUCCESSThe user has successfully completed the MFA flow (when the enhancedMFA=true customization parameter is enabled).
INSTITUTION_SELECTEDThe user has selected their financial institution.
INVALID_INSTITUTIONA financial institution is invalid.
INSTITUTION_NOT_AVAILABLEA financial institution is not available.
INVALID_SECURITY_RESPONSEThe user has failed the MFA challenge.
MAXIMUM_RETRY_REACHEDThe user has reached the maximum number of retries permitted (when the [maximumRetry={number}](https://docs.flinks.com/docs/customize-your-integration#maximumretry) customization parameter is enabled).
QUESTION_NOT_FOUNDThe MFA challenge is returned by the API. This page contains metadata that specifies which MFA challenge the user is presented with (mfaTypes).
REDIRECTThe user has successfully completed the account connection flow and are redirected. This includes the URL, loginId, requestId, and institution. For example:

step: 'REDIRECT' URL: '<https://clientops-iframe.private.fin.ag/v2/Result/…-4e36-795b-08db4111f24d&institution=FlinksCapital'>, loginId: 'b92b2bbd-31f8-4e36-795b-08db4111f24d', requestId: 'de4d15c4-5738-4004-81b2-fb28c5e4c1a0', institution: 'FlinksCapital'
RETRY_COUNTThe user has failed the authorization process and the number of retries are recorded, starting from 0.
SESSION_NONEXISTENT or SESSION_EXPIREDThe session has expired.
SESSION_STORAGE_BLOCKEDLegacy cookie management (deprecated).
SESSION_STORAGE_BLOCKED_RETRYLegacy cookie management (deprecated).
SKIP_ENHANCED_MFAThe user has skipped the unanswered MFA questions (when the enhancedMFA=true customization parameter is enabled).
SUBMIT_ANSWER_MFA_QUESTIONSThe user has submitted the unanswered MFA questions.
SUBMIT_CREDENTIALThe form is valid and the user clicks the 'Continue' button.
SUBMIT_GET_MFA_QUESTIONSWe've received unanswered MFA questions (when the enhancedMFA=true customization parameter is enabled).
SUBMIT_MFAThe user has submitted the MFA questions.
BACK_SECTIONThe user has clicked on the 'Back' button (when the [backEnable](https://docs.flinks.com/docs/customize-your-integration#layout-customization) customization parameter is enabled).
FEEDBACKThe user has opted to provide feedback about their connection experience.
POPUP_BLOCKEDThe OAuth connection was blocked.
POPUP_CLOSEDThe OAuth connection was closed.
POPUP_OPENEDThe OAuth connection was initiated.
POPUP_UPDATEDThe OAuth connection has been updated.

List of API events

You'll receive the following Flinks Codes if an event is triggered in the API.

HTTP Status CodeFlinks CodeDescriptionMessageSteps to Reproduce
200N/AThe connection was successful.Complete a successful request.
202OPERATION_PENDINGThe process is ongoing in the background. At this point your flow must change to the async endpointYour operation is still processing.Perform a cached flow immediately after Authorizing a new account
202OPERATION_DISPATCHEDYour 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 jobsHave a live request to gather GetAccountDetails in more than 210 seconds
400SESSION_NONEXISTENTA request was made with an expired RequestIdInputs session id or card if were not found.Use an old RequestId for a new request
400CARD_IN_USEAn operation was requested while the account is still being processed.Call the DeleteCard endpoint immediately after Authorizing a new account
401ACCESS_DENIEDAuthentication was unsuccessful
401INVALID_LOGINThe provided LoginId is invalidThe LoginId provided is either invalid or does not belong to the CustomerIdCall the Authorize endpoint using a non existent LoginId
401INVALID_LOGINThe provided username or/and password is/are invalidThe card number (username) or password provided is invalidCall the Authorize endpoint using non valid credentials
401INVALID_REQUESTCredentials 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.
401INVALID_SECURITY_RESPONSE_NO_RETRYThe user has provided incorrect or incomplete MFA answers and cannot retry
401INVALID_USERNAMEThe username provided was different from what the bank expectedProvide an invalid username to an Authorize request
401INVALID_PASSWORDThe password provided was different from what the bank expectedProvide an invalid password to an Authorize request
401INVALID_SECURITY_RESPONSEThe MFA response provided was different from what the bank expectedProvide an invalid MFA answer to an Authorize request
401QUESTION_NOT_FOUNDThe MFA prompt doesn't have a stored answer
401RETRY_LATERFlinks was not able to open a connection with the selected financial institutionFlinks Capital Username: test_service_unavailable Password: Everyday
401TOO_MANY_REQUESTSThe endpoint has received too many requests in a given amount of time
401UNKNOWN_CHALLENGE_KEYThe /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
401CONCURRENT_SESSIONAnother session is already opened with this LoginIdOpen two requests simultaneously with the same account
401UNAUTHORIZEDThe card was not authorized. Either there is a problem with bank, or the GetAccountsDetail endpoint was called before authorizedYou need to be authorized in the bank account before going further.Call the GetAccountsDetail endpoint during an MFA prompt without answering the MFA question
401UNHANDLEDAn error was encountered that cannot be handled or processed
401DISABLED_LOGINThe account has been deactivated by the financial institution. The account holder must contact their bankLog into a deactivated account
401NEW_ACCOUNTThe end user must take action directly on their online banking before connecting an account with FlinksLogin to an account where the user must take action on the bank's website (e.g. to accept a consent form)
401SESSION_EXPIREDThe RequestId expired after 8 mins of inactivity during Authorize or 30 mins timeout for data processingWait at least 8 minutes before responding to MFA
401ALREADY_AUTHORIZEDWhen the /Authorize endpoint is called after the user has already been authorizedAnswer an MFA for an already authorized requestid
401SECURITYRESPONSES_INCOMPLETENot all the prompted MFA questions had answers in the reponse requestNot answer all MFA questions prompted in 3 question MFA prompt
404NO_TRANSACTIONThe account does not have any transactionsNo transactions were found.Perform an Attributes request for an account with no GetAccountDetails previously processed
405DISABLED_INSTITUTIONThe selected financial institution is not available
500AGGREGATION_ERRORFlinks had an unexpected error and could not process your request
501METHOD_NOT_AVAILABLEThe requested API is not currently enabled in your instance. Kindly contact us if you wish to use this feature.

For more information about what each of these events look like in the Flinks Connect flow, see the examples on our help article page.