Use an Event Listener

The GEFT widget triggers events based on authentication responses and different steps that the user completes within the payment flow. We recommend adding an Event Listener to your GEFT widget integration to track your users’ progress and improve their overall experience. As a user progresses through the guaranteed payment flow, you’ll be notified of all successful (and unsuccessful) attempts to complete a payment. 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 GEFT widget integration, place the following script on the same page as your GEFT widget:

html

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

React Native WebView

When the GEFT widget is loaded as the top-level page of a React Native WebView, add webview=true to the URL:

https://[instance]-iframe.private.fin.ag/payment-[instance]/?sessionId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&webview=true

Events are emitted to window.ReactNativeWebView.postMessage instead of window.postMessage, so handle them in the WebView’s onMessage handler rather than a message listener. Each event arrives as a JSON string. The events and their order are unchanged from the web.

window.ReactNativeWebView is injected into the main frame only, so the widget must be the WebView’s top-level page and not nested in an iframe.

Reviewing your Event Listener data

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

A JavaScript event, which indicates a user event during the payment flow
Widget state changes, which indicate progress through the guarantee process

Read the lists below for information on what sorts of event data you can receive for user events and widget state changes. We will notify you of the following user events in the GEFT widget:

EVENT NAME	DESCRIPTION	TERMINATING EVENT
`APP_MOUNTED`	The payment experience has loaded and is visible to your customer.	No
`APP_INITIATED`	The payment flow has been initiated. Carries `referenceId` (the value you set when creating the session).	No
`COMPONENT_LOAD_CONSENT`	The customer is shown the consent / authorization screen.	No
`CONSENT_DISABLED`	Emitted when using a custom consent screen instead of the Flinks-provided one (optional configuration).	No
`SET_SESSION`	Session details are shared with the page hosting the payment flow.	No
`COMPONENT_ACCEPT_TERMS`	The customer ticked the terms checkbox on the consent screen.	No
`COMPONENT_DENY_TERMS`	The customer un-ticked the terms checkbox on the consent screen.	No
`COMPONENT_DENY_CONSENT`	The customer declined consent and is leaving the flow.	Yes
`COMPONENT_ACCEPT_CONSENT`	The customer agreed and is moving on to link their bank.	No

Institution Selection

EVENT NAME	DESCRIPTION	TERMINATING EVENT
`SESSION_INITIALIZED`	A payment session has been created for this customer. Includes the session and user IDs.	No
`COMPONENT_LOAD_INSTITUTION_SELECTOR`	The customer is shown the list of banks to choose from.	No
`INSTITUTION_DEFAULT_NOT_FOUND`	A pre-set bank couldn’t be found, so the customer picks one manually.	No
`INSTITUTION_SEARCH_RESULT`	The customer’s bank search returned one or more matches.	No
`INSTITUTION_SEARCH_NO_RESULT`	The customer’s bank search returned nothing.	No

Credential

EVENT NAME	DESCRIPTION	TERMINATING EVENT
`INSTITUTION_SELECTED`	The user has selected their financial institution.	No
`COMPONENT_LOAD_CREDENTIAL`	The customer is shown their bank’s sign-in screen.	No
`COMPONENT_BACK_SESSION`	The customer stepped back to a previous screen.	No
`COMPONENT_CLICK_RESET_PASSWORD`	The customer clicked the “forgot / reset password” link.	No
`COMPONENT_LOAD_CREDENTIAL_RETRY`	The sign-in screen is shown again after a failed attempt.	No
`SUBMIT_CREDENTIAL`	The user has submitted their bank login credentials.	No

Aggregation Errors

These problems reach you in two different shapes. Two are step events - the payment flow reporting the customer’s progress through their sign-in attempts: RETRY_COUNT (which attempt they’re on, sent earlier during sign-in) and MAXIMUM_RETRY_REACHED (they’ve used them all up). Both arrive on the event’s step field. Everything else here is a flinksCode, a standardized reason code, shared across Flinks, for why the bank turned the sign-in away, delivered on the flinksCode field instead. In short: read step for the two progress signals, and flinksCode for every other problem in this list.

EVENT NAME	DESCRIPTION	TERMINATING EVENT
`MAXIMUM_RETRY_REACHED`	The customer used up all their allowed sign-in attempts.	Yes
`RETRY_COUNT`	Tells you which sign-in attempt the customer is on.	Yes (after 3 attempts)
`INVALID_USERNAME`	The username didn’t work. The customer can try again.	No
`INVALID_PASSWORD`	The password didn’t work. The customer can try again.	No
`INVALID_LOGIN`	The sign-in details didn’t work. The customer can try again.	No
`RETRY_LATER`	The bank is temporarily unavailable. Ask the customer to try again later.	No
`TOO_MANY_REQUESTS`	Too many attempts in a short time - the customer is temporarily blocked.	Yes
`ACCESS_DENIED`	The bank refused access for this customer.	Yes
`INVALID_SECURITY_RESPONSE_NO_RETRY`	A security question was answered incorrectly with no attempts left.	Yes
`FORBIDDEN`	This customer or account isn’t permitted to continue.	Yes
`DISABLED_LOGIN`	Sign-in is disabled for this customer at their bank.	Yes
`NEW_ACCOUNT`	The account is too new to be used for this payment.	Yes

MFA

EVENT NAME	DESCRIPTION	TERMINATING EVENT
`COMPONENT_LOAD_MFA`	The customer is shown a security challenge — a one-time code or security question.	No
`SUBMIT_MFA`	The user has submitted multi-factor authentication answers.	No
`INVALID_SECURITY_RESPONSE`	The security answer was wrong, but the customer can try again.	No
`COMPONENT_LOAD_MFA_RETRY`	The verification screen is shown again for another attempt.	No
`RESUME_SESSION`	The customer is returning to a session already in progress and picks up where they left off.	No
`SESSION_EXPIRED`	The aggregation session is no longer valid. It timed out or can’t be found. The customer can continue within the allowed window of time.	No (user can try to authenticate again)

Account Selector

EVENT NAME	DESCRIPTION	TERMINATING EVENT
`COMPONENT_LOAD_ACCOUNT_SELECTION`	The customer is shown their accounts to choose from.	No
`ACCOUNT_SELECTED`	The user has selected which bank account to use for the payment.	No
`ACCOUNT_VERIFICATION`	The selected account is being verified.	No
`REDIRECT`	The journey moves from linking the bank to the payment step.	No

Deposit

EVENT NAME	DESCRIPTION	TERMINATING EVENT
`COMPONENT_DEPOSIT_SCREEN_LOADED`	The customer is shown the amount screen.	No
`COMPONENT_DEPOSIT_AMOUNT_ENTERED`	The customer entered an amount.	No
`COMPONENT_DEPOSIT_AMOUNT_EDITED`	The customer changed the amount they’d entered.	No
`COMPONENT_DEPOSIT_CONTINUE`	The user has clicked to continue after entering or confirming the payment amount.	No

Next Best Offer (NBO)

EVENT NAME	DESCRIPTION	TERMINATING EVENT
`COMPONENT_NBO_LOADED`	The requested amount isn’t available, so the customer is shown an alternative offer.	No
`COMPONENT_NBO_CONTINUE`	The customer accepted the alternative offer.	No
`COMPONENT_NBO_RETURN_TO_CLIENT_SELECTED`	The user has chosen to return to your application for alternative payment methods.	Yes

Guarantee & Review

EVENT NAME	DESCRIPTION	TERMINATING EVENT
`GUARANTEE_OFFERED`	Flinks can guarantee the payment and has presented the guarantee offer to the user.	No
`COMPONENT_LOAD_PAYMENT_REVIEW`	The customer is shown a summary to review before confirming.	No
`COMPONENT_ACCEPT_PAYMENT_REVIEW`	The customer approved the summary.	No
`COMPONENT_REJECT_PAYMENT_REVIEW`	The customer rejected the summary and is leaving the flow.	No
`PAD_LEGAL`	The customer is shown the pre-authorized debit agreement text.	No
`COMPONENT_LOAD_PAD_AGREEMENT`	The customer is shown the agreement to sign and accept.	No
`COMPONENT_PAD_DOWNLOADED`	The Pre-Authorized Debit (PAD) agreement has been downloaded by the user.	No
`COMPONENT_PAD_REJECTED`	The customer declined the agreement.	No
`COMPONENT_PAD_WARNING_SCREEN_LOADED`	The customer is shown an “Are you sure you want to exit?” prompt.	No
`COMPONENT_PAD_WARNING_SCREEN_EXIT`	The user has opted not to accept the PAD agreement and has chosen to exit the flow.	No
`COMPONENT_PAD_WARNING_SCREEN_RETURN`	The customer chose to stay and continue.	No
`COMPONENT_AGREE_TERMS_PAD`	The customer ticked the agreement’s terms checkbox.	No
`COMPONENT_DENY_TERMS_PAD`	The customer un-ticked the agreement’s terms checkbox.	No
`COMPONENT_PAD_ACCEPTED`	The customer signed and accepted the agreement.	No
`SUCCESS`	The user has successfully completed the payment flow. The iframe should be closed.	Yes

Errors

EVENT NAME	DESCRIPTION	TERMINATING EVENT
`PAYMENT_FAILED`	The payment couldn’t be completed. Failure reasons can include: `IDENTITY_MISMATCH`, `ACCOUNT_NOT_ELIGIBLE`, `INSUFFICIENT_BALANCE`	Yes
`COMPONENT_OTHER_FUNDING_OPTIONS_SELECTED`	The customer chose to use a different payment method and left the flow.	Yes

Event Examples

Flow Events

APP_INITIATED

{
  "step": "APP_INITIATED",
  "referenceId": "{{referenceId}}"
}

INSTITUTION_SELECTED

{
  "step": "INSTITUTION_SELECTED"
}

SUBMIT_CREDENTIAL

{
  "step": "SUBMIT_CREDENTIAL"
}

ACCOUNT_SELECTED

{
  "step": "ACCOUNT_SELECTED"
}

Guarantee Events

GUARANTEE_OFFERED

{
  "step": "GUARANTEE_OFFERED"
}

PAYMENT_FAILED (Terminating)

{
  "step": "PAYMENT_FAILED"
}

Terminal Events

SUCCESS (Terminating)

{
  "step": "SUCCESS"
}

Implementation Examples

Basic Event Handling

<script>
window.addEventListener('message', function(e) {
  const eventData = e.data;

  switch(eventData.step) {
    case 'APP_INITIATED':
      console.log('Payment flow initiated');
      hideLoadingSpinner();
      break;

    case 'INSTITUTION_SELECTED':
      console.log('User selected bank');
      showProgress('Connecting to bank...');
      break;

    case 'GUARANTEE_OFFERED':
      console.log('Payment guaranteed');
      showProgress('Payment approved, completing...');
      break;

    case 'SUCCESS':
      console.log('Payment completed successfully');
      closeWidget();
      redirectToSuccess();
      break;

    case 'PAYMENT_FAILED':
      console.log('Payment declined');
      closeWidget();
      showAlternativePaymentOptions();
      break;
  }
});
</script>

Error Handling and Timeouts

let widgetTimeout;
const WIDGET_TIMEOUT_MS = 3600000; // 60 minutes

window.addEventListener('message', function(e) {
  const eventData = e.data;

  // Reset timeout on any event
  clearTimeout(widgetTimeout);

  // Handle the event
  handleGeftEvent(eventData);

  // Set new timeout for non-terminal events
  const terminalEvents = ['SUCCESS', 'PAYMENT_FAILED', 'CLOSE',
                         'COMPONENT_PAD_WARNING_SCREEN_EXIT'];

  if (!terminalEvents.includes(eventData.step)) {
    widgetTimeout = setTimeout(handleWidgetTimeout, WIDGET_TIMEOUT_MS);
  }
});

function handleWidgetTimeout() {
  console.warn('GEFT widget timeout - no events received');

  // Show timeout message to user
  showTimeoutMessage('The payment process is taking longer than expected.');

  // Offer alternative options
  showAlternativePaymentOptions();
}

Event Flow Examples

Successful Payment Flow

APP_INITIATED - Payment flow initiated
INSTITUTION_SELECTED - User selects their bank
SUBMIT_CREDENTIAL - User enters bank credentials
SUBMIT_MFA - User completes multi-factor authentication (if required)
ACCOUNT_SELECTED - User selects the account for payment
COMPONENT_DEPOSIT_CONTINUE - User confirms payment amount
GUARANTEE_OFFERED - Flinks approves the guarantee
COMPONENT_PAD_DOWNLOADED - User signs PAD agreement
SUCCESS - Payment completed successfully

Guarantee Declined Flow

APP_INITIATED - Payment flow initiated
INSTITUTION_SELECTED - User selects their bank
SUBMIT_CREDENTIAL - User enters bank credentials
ACCOUNT_SELECTED - User selects account
COMPONENT_DEPOSIT_CONTINUE - User confirms amount
PAYMENT_FAILED - Flinks cannot guarantee the payment
COMPONENT_OTHER_FUNDING_OPTIONS_SELECTED - User chooses alternative methods

Testing Event Handling

During development, test event handling with all scenarios in the sandbox environment. Use the test cases provided in the Sandbox Guide to verify proper event handling for both successful and failed flows. Test the following scenarios:

Happy path: Complete successful payment flow
Guarantee failure: Handle declined guarantees gracefully
User abandonment: Handle when users close the widget
Network issues: Handle timeouts and connectivity problems
PAD decline: Handle when users don’t accept the agreement

GEFT Widget: Widget configuration and setup
Setup Guide: Complete implementation walkthrough
Sandbox Guide: Testing procedures and test data

Getting Started

AI

Connect

Enrich

Pay

Webhooks

Upload

Dashboard

Outbound

Security

Support

Add the Event Listener to your Integration

React Native WebView

Reviewing your Event Listener data

Institution Selection

Credential

Aggregation Errors

MFA

Account Selector

Deposit

Next Best Offer (NBO)

Guarantee & Review

Errors

Event Examples

Flow Events

Guarantee Events

Terminal Events

Implementation Examples

Basic Event Handling

Error Handling and Timeouts

Event Flow Examples

Successful Payment Flow

Guarantee Declined Flow

Testing Event Handling

​Add the Event Listener to your Integration

​React Native WebView

​Reviewing your Event Listener data

​Getting started & Consent

​Institution Selection

​Credential

​Aggregation Errors

​MFA

​Account Selector

​Deposit

​Next Best Offer (NBO)

​Guarantee & Review

​Errors

​Event Examples

​Flow Events

​Guarantee Events

​Terminal Events

​Implementation Examples

​Basic Event Handling

​Error Handling and Timeouts

​Event Flow Examples

​Successful Payment Flow

​Guarantee Declined Flow

​Testing Event Handling

​Related Documentation

Add the Event Listener to your Integration

React Native WebView

Reviewing your Event Listener data

Getting started & Consent

Institution Selection

Credential

Aggregation Errors

MFA

Account Selector

Deposit

Next Best Offer (NBO)

Guarantee & Review

Errors

Event Examples

Flow Events

Guarantee Events

Terminal Events

Implementation Examples

Basic Event Handling

Error Handling and Timeouts

Event Flow Examples

Successful Payment Flow

Guarantee Declined Flow

Testing Event Handling

Related Documentation