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 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. |
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 to return. |
COMPONENT_HELP2FA_TROUBLESHOOTING | The user has clicked on the troubleshooting tips hyperlink and has viewed the troubleshouting 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 consentEnable=true 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](https://docs.flinks.com/docs/customize-your-integration#layout-customization) 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}](https://docs.flinks.com/docs/customize-your-integration#maximumretry) 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. 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_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. |
BACK_SECTION | The user has clicked on the 'Back' button (when the [backEnable](https://docs.flinks.com/docs/customize-your-integration#layout-customization) 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. |
List of API events
You'll receive the following Flinks Codes if an event is triggered in the API.
HTTP Status Code | Flinks Code | Description | Message | Steps to Reproduce |
---|---|---|---|---|
200 | N/A | The connection was successful. | Complete a successful request. | |
202 | OPERATION_PENDING | The process is ongoing in the background. At this point your flow must 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 | |
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 | Flinks Capital Username: test_service_unavailable Password: Everyday | |
401 | TOO_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 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 | |
401 | SECURITYRESPONSES_INCOMPLETE | Not all the prompted MFA questions had answers in the reponse request | 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 more information about what each of these events look like in the Flinks Connect flow, see the examples on our help article page.
Updated 2 months ago