Skip to main content
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 NAMEDESCRIPTIONTERMINATING EVENT
APP_MOUNTEDGEFT widget has successfully loaded and is ready for user interaction.No
CONSENT_DISABLEDEmitted when using a custom consent screen instead of the Flinks-provided one (optional configuration).No
INSTITUTION_SELECTEDThe user has selected their financial institution.No
SUBMIT_CREDENTIALThe user has submitted their bank login credentials.No
SUBMIT_MFAThe user has submitted multi-factor authentication answers.No
ACCOUNT_SELECTEDThe user has selected which bank account to use for the payment.No
COMPONENT_DEPOSIT_CONTINUEThe user has clicked to continue after entering or confirming the payment amount.No
GUARANTEE_OFFEREDFlinks can guarantee the payment and has presented the guarantee offer to the user.No
COMPONENT_PAD_DOWNLOADEDThe Pre-Authorized Debit (PAD) agreement has been downloaded or signed by the user.No
SUCCESSThe user has successfully completed the GEFT payment flow. The iframe should be closed.Yes
GUARANTEE_FAILEDFlinks cannot guarantee the transaction. The user should be offered alternative payment methods.Yes
COMPONENT_PAD_WARNING_SCREEN_EXITThe user has opted not to accept the PAD agreement and has chosen to exit the flow.Yes
COMPONENT_OTHER_FUNDING_OPTIONS_SELECTEDFlinks cannot guarantee the transaction and the user has selected other funding options.Yes
COMPONENT_NBO_RETURN_TO_CLIENT_SELECTEDThe user has chosen to return to your application for alternative payment methods.Yes
CLOSEThe user has clicked the close button (X) to exit the widget.Yes

​
Event Examples

​
Flow Events

APP_MOUNTED 
{
  "Step": "APP_MOUNTED",
  "sessionId": "{{sessionId}}"
}
INSTITUTION_SELECTED 
{
  "Step": "INSTITUTION_SELECTED",
  "sessionId": "{{sessionId}}"
}
SUBMIT_CREDENTIAL 
{
  "Step": "SUBMIT_CREDENTIAL",
  "sessionId": "{{sessionId}}"
}
ACCOUNT_SELECTED 
{
  "Step": "ACCOUNT_SELECTED",
  "sessionId": "{{sessionId}}"
}

​
Guarantee Events

GUARANTEE_OFFERED 
{
  "Step": "GUARANTEE_OFFERED",
  "sessionId": "{{sessionId}}"
}
GUARANTEE_FAILED (Terminating) 
{
  "Step": "GUARANTEE_FAILED",
  "sessionId": "{{sessionId}}"
}

​
Terminal Events

SUCCESS (Terminating) 
{
  "Step": "SUCCESS",
  "sessionId": "{{sessionId}}",
  "requestId": "{{requestId}}"
}
CLOSE (Terminating) 
{
  "Step": "CLOSE",
  "sessionId": "{{sessionId}}"
}

​
Implementation Examples

​
Basic Event Handling

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

  switch(eventData.Step) {
    case 'APP_MOUNTED':
      console.log('GEFT widget loaded');
      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
window.addEventListener('message', function(e) {
  const eventData = e.data;

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

  // Handle specific business logic
  switch(eventData.Step) {
    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) {
  // Close GEFT widget
  document.getElementById('geft-widget').style.display = 'none';

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

  // Redirect to confirmation page
  setTimeout(() => {
    window.location.href = `/payment-confirmation?requestId=${eventData.requestId}`;
  }, 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

  1. APP_MOUNTED - Widget loads successfully
  2. INSTITUTION_SELECTED - User selects their bank
  3. SUBMIT_CREDENTIAL - User enters bank credentials
  4. SUBMIT_MFA - User completes multi-factor authentication (if required)
  5. ACCOUNT_SELECTED - User selects the account for payment
  6. COMPONENT_DEPOSIT_CONTINUE - User confirms payment amount
  7. GUARANTEE_OFFERED - Flinks approves the guarantee
  8. COMPONENT_PAD_DOWNLOADED - User signs PAD agreement
  9. SUCCESS - Payment completed successfully

​
Guarantee Declined Flow

  1. APP_MOUNTED - Widget loads successfully
  2. INSTITUTION_SELECTED - User selects their bank
  3. SUBMIT_CREDENTIAL - User enters bank credentials
  4. ACCOUNT_SELECTED - User selects account
  5. COMPONENT_DEPOSIT_CONTINUE - User confirms amount
  6. GUARANTEE_FAILED - Flinks cannot guarantee the payment
  7. COMPONENT_OTHER_FUNDING_OPTIONS_SELECTED - User chooses alternative methods

​
User Exit Flow

  1. APP_MOUNTED - Widget loads successfully
  2. INSTITUTION_SELECTED - User selects their bank
  3. 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