Events and callbacks

Observe Connect.js loading, user actions, errors, exits, and successful completion.

Connect.js exposes four callbacks. Each callback marks a different point in the widget lifecycle.

Callback summary

Callback	Required	Called when	Arguments
onSuccess	Yes	Account linking or a payment flow completes.	One result object
onClose	No	The widget is hidden through a user exit, success, or close().	None
onLoad	No	The widget iframe mounts and loads.	None
onEvent	No	A supported lifecycle or user-action event occurs.	eventName, data

onSuccess

Account linking returns an object containing a short-lived code.

onSuccess: ({ code }) => sendCodeToBackend(code)

A payment flow returns charge data instead. Keep flow-specific handlers separate so the code does not assume one response shape for both.

onClose

onClose: () => {
  setConnectOpen(false)
}

close() invokes this callback, including when the SDK closes after success.

onLoad

Use onLoad to enable the trigger only after the widget is ready.

onLoad: () => {
  setLinkButtonEnabled(true)
}

onEvent

onEvent: (eventName, data) => {
  console.log(eventName, data)
}

The current SDK maps widget messages to these event names:

Event	Meaning
LOADED	The widget iframe loaded.
OPENED	The widget became visible.
EXIT	The user exited the flow.
ERROR	The widget reported an error.
INSTITUTION_SELECTED	The user selected an institution.
AUTH_METHOD_SWITCHED	The user changed authentication method.
SUBMIT_CREDENTIALS	The user submitted the institution login step.
SUBMIT_MFA	The user submitted a multi-factor authentication step.
ACCOUNT_LINKED	The widget linked an account.
ACCOUNT_SELECTED	The user selected an account.
SUCCESS	The SDK received its account-linked or charge-complete success message.

Payload handling

Payload fields depend on the event and may include an institution, authentication method, error metadata, page name, selected-account count, timestamp, or the optional reference supplied during setup.

Read event data defensively:

onEvent: (eventName, data = {}) => {
  if (eventName === "INSTITUTION_SELECTED") {
    analytics.track("mono_institution_selected", {
      institutionId: data.institution?.id,
      authMethod: data.authMethod
    })
  }

  if (eventName === "ERROR") {
    errorTracker.captureMessage("Mono Connect error", {
      extra: {
        errorType: data.errorType,
        errorMessage: data.errorMessage,
        reference: data.reference
      }
    })
  }
}

Do not record credentials, MFA values, BVNs, account numbers, or unreviewed full event payloads. Define an allowlist of fields for analytics and logs.

Success semantics

ACCOUNT_LINKED is useful telemetry about widget progress. Use onSuccess to obtain the auth code and start the backend exchange. Treat the backend’s successful exchange and persistence as application-level completion.