Widget integration

Setup

The Capital product UI integrates seamlessly with the Platform's interface through an iframe.

To ensure a cohesive user experience, the iframe UI is fully customized to align with the Platform's visual design system. Each element is tailored by us to fit within the Platform's branding while preserving an optimal flow for maximum conversion.

The only prerequisite to render is a valid signed link, which Platform can obtain for a Business using get Get current Offer API.

<iframe src="{signedLink}" />

Events

The iframe reports the following events to the parent window via window.postMessage():

Event	Payload	When
iframe rendered	`{ "type": "INITIALIZED" }`	The iframe has loaded and is ready
Offers are shown	`{ "type": "OFFERS_SHOWN" }`	The user sees the offer overview or renewal page
Onboarding opened	`{ "type": "ONBOARDING:OPENED", "data": { "onboardingId": "<uuid>" } }`	The user enters the onboarding flow
Onboarding submitted	`{ "type": "ONBOARDING:SUBMITTED", "data": { "onboardingId": "<uuid>" } }`	The user completes the onboarding bank connection step

All events fire at most once per iframe mount.

Prerequisites

To receive iframe events, the Platform's must provide finmid a hostname which will be the ancestor of the iframe.

Capital iframe will send events using window.parent.postMessage(event, frameTargetOrigin), or special bridge objects when embedded in mobile apps.

The host window should listen for events like:

window.addEventListener("message", (event) => {
  if (event.origin !== "<finmid-iframe-origin>") return;
  console.log("Capital event:", event.data);
});