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>

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_INITIATED`	The payment flow has been initiated. Carries `referenceId` (the value you set when creating the session).	No
`CONSENT_DISABLED`	Emitted when using a custom consent screen instead of the Flinks-provided one (optional configuration).	No
`INSTITUTION_SELECTED`	The user has selected their financial institution.	No
`SUBMIT_CREDENTIAL`	The user has submitted their bank login credentials.	No
`SUBMIT_MFA`	The user has submitted multi-factor authentication answers.	No
`ACCOUNT_SELECTED`	The user has selected which bank account to use for the payment.	No
`COMPONENT_DEPOSIT_CONTINUE`	The user has clicked to continue after entering or confirming the payment amount.	No
`GUARANTEE_OFFERED`	Flinks can guarantee the payment and has presented the guarantee offer to the user.	No
`COMPONENT_PAD_DOWNLOADED`	The Pre-Authorized Debit (PAD) agreement has been downloaded or signed by the user.	No
`SUCCESS`	The user has successfully completed the GEFT payment flow. The iframe should be closed.	Yes
`GUARANTEE_FAILED`	Flinks cannot guarantee the transaction. The user should be offered alternative payment methods.	Yes
`COMPONENT_PAD_WARNING_SCREEN_EXIT`	The user has opted not to accept the PAD agreement and has chosen to exit the flow.	Yes
`COMPONENT_OTHER_FUNDING_OPTIONS_SELECTED`	Flinks cannot guarantee the transaction and the user has selected other funding options.	Yes
`COMPONENT_NBO_RETURN_TO_CLIENT_SELECTED`	The user has chosen to return to your application for alternative payment methods.	Yes
`CLOSE`	The user has clicked the close button (X) to exit the widget.	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"
}

GUARANTEE_FAILED (Terminating)

{
  "step": "GUARANTEE_FAILED"
}

Terminal Events

SUCCESS (Terminating)

{
  "step": "SUCCESS"
}

CLOSE (Terminating)

{
  "step": "CLOSE"
}

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 'GUARANTEE_FAILED':
      console.log('Guarantee declined');
      closeWidget();
      showAlternativePaymentOptions();
      break;

    case 'CLOSE':
      console.log('User closed widget');
      closeWidget();
      break;
  }
});
</script>

Advanced Event Tracking

// Enhanced event listener with analytics
let paymentReferenceId = null;

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

  // Track all GEFT events
  if (eventData.step) {
    analytics.track('GEFT Widget Event', {
      step: eventData.step,
      timestamp: new Date().toISOString()
    });
  }

  // Handle specific business logic
  switch(eventData.step) {
    case 'APP_INITIATED':
      // Capture the referenceId to use when the payment completes
      paymentReferenceId = eventData.referenceId;
      break;

    case 'GUARANTEE_FAILED':
      handleGuaranteeFailure(eventData);
      break;

    case 'SUCCESS':
      handlePaymentSuccess(eventData);
      break;

    case 'COMPONENT_PAD_WARNING_SCREEN_EXIT':
      handlePadDeclined(eventData);
      break;
  }
});

function handleGuaranteeFailure(eventData) {
  // Close GEFT widget
  document.getElementById('geft-widget').style.display = 'none';

  // Show user-friendly message
  showMessage('We cannot guarantee this payment method. Please choose an alternative.');

  // Enable other payment options
  enableCreditCardPayment();
  enableETransferPayment();
}

function handlePaymentSuccess(eventData) {
  // Read the payment sessionId back from the widget URL you embedded
  const widget = document.getElementById('geft-widget');
  const sessionId = new URL(widget.src).searchParams.get('sessionId');

  // Close GEFT widget
  widget.style.display = 'none';

  // Show success message
  showSuccessMessage('Payment completed successfully!');

  // Redirect to confirmation page
  setTimeout(() => {
    window.location.href = `/payment-confirmation?sessionId=${sessionId}&referenceId=${paymentReferenceId}`;
  }, 2000);
}

Error Handling and Timeouts

let widgetTimeout;
const WIDGET_TIMEOUT_MS = 300000; // 5 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', 'GUARANTEE_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
GUARANTEE_FAILED - Flinks cannot guarantee the payment
COMPONENT_OTHER_FUNDING_OPTIONS_SELECTED - User chooses alternative methods

User Exit Flow

APP_INITIATED - Payment flow initiated
INSTITUTION_SELECTED - User selects their bank
CLOSE - User clicks X to close widget

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

Reviewing your Event Listener data

Event Examples

Flow Events

Guarantee Events

Terminal Events

Implementation Examples

Basic Event Handling

Advanced Event Tracking

Error Handling and Timeouts

Event Flow Examples

Successful Payment Flow

Guarantee Declined Flow

User Exit Flow

Testing Event Handling

​Add the Event Listener to your Integration

​Reviewing your Event Listener data

​Event Examples

​Flow Events

​Guarantee Events

​Terminal Events

​Implementation Examples

​Basic Event Handling

​Advanced Event Tracking

​Error Handling and Timeouts

​Event Flow Examples

​Successful Payment Flow

​Guarantee Declined Flow

​User Exit Flow

​Testing Event Handling

​Related Documentation

Add the Event Listener to your Integration

Reviewing your Event Listener data

Event Examples

Flow Events

Guarantee Events

Terminal Events

Implementation Examples

Basic Event Handling

Advanced Event Tracking

Error Handling and Timeouts

Event Flow Examples

Successful Payment Flow

Guarantee Declined Flow

User Exit Flow

Testing Event Handling

Related Documentation