Getting Started

Installation

Install the CFC SDK using your preferred package manager:

pnpm add @melio-eng/cfc-sdk

npm install @melio-eng/cfc-sdk

yarn add @melio-eng/cfc-sdk

Basic Usage

The SDK provides a CfcClient class that manages the entire iframe lifecycle — creating the iframe, handling authentication, dimension sync, scroll forwarding, URL sync, and all message handling. You just provide a container element and your config.

import { CfcClient, Environment, IntegrationMode, NavigationTarget } from "@melio-eng/cfc-sdk";

const client = new CfcClient({
	container: document.getElementById("cfc-container")!,
	environment: Environment.STAGING,
	token: "<your-auth-token>",
	tenant: "your-tenant-id",
	mode: IntegrationMode.FULL_PAGE,
	target: NavigationTarget.VIEW_PAYMENTS,

	// Optional callbacks — the SDK handles everything else automatically
	onSessionExpired: () => {
		window.location.href = "/login";
	},
	onExitRequested: (originator) => {
		client.destroy();
		window.location.href = "/dashboard";
	},
});

client.init();

// Navigate programmatically
client.navigateTo(NavigationTarget.viewBill("bill-123"));

// Cleanup when done
client.destroy();

That's it. The SDK automatically handles:

• Creating the iframe inside your container
• Constructing the auth URL
• Dimension synchronization (resize, scroll, content size changes)
• Navigation callbacks (react to CFC page changes)
• Forwarding scroll position to CFC
• All CFC message types

Configuration

The CfcClientConfig interface accepts the following options:

Option	Type	Required	Description
container	HTMLElement	Yes	DOM element where the SDK creates the iframe
environment	Environment	Yes	Target environment (use Environment constants)
token	string	Yes	Authentication token passed to the CFC auth endpoint
tenant	string	Yes	Tenant identifier for multi-tenant environments
mode	IntegrationMode	Yes	Integration mode (use IntegrationMode constants)
target	string	No	Initial navigation target (use NavigationTarget helpers)
headerHeight	number	No	Height of the host app header in pixels (partial mode)
allowedOrigin	string	No	Override origin for message validation

Event Callbacks

Callback	Type	Description
onLoaded	() => void	CFC iframe has finished loading and is ready
onNavigated	(target, targetAction?) => void	CFC navigated to a new page
onPaymentSuccess	() => void	Payment was successfully scheduled
onAuthenticationError	(reason, message) => void	Authentication failed
onSessionExpired	() => void	CFC session expired
onExitRequested	(originator) => void	User wants to leave CFC
onUpgradeRequest	(featureName, returnUrl) => void	Subscription upgrade needed
onUserActivePing	() => void	User is active in the iframe
onMessage	(message) => void	Low-level: all CFC messages
onError	(error) => void	SDK-level errors

Integration Modes

The SDK supports two integration modes:

• Full Page -- CFC owns the full vertical space. The host can still have a sidebar and header — as long as there's no host content above or below the iframe competing for vertical scroll.
• Partial -- The host has its own content above or below the CFC iframe, creating a shared vertical scroll. The SDK handles scroll coordination and dynamic iframe resizing.

See the Integration Guide for details on both modes. The SDK handles dimension sync, scroll forwarding, and all message handling automatically.

Next Steps

• Integration Guide
• DIY Integration (without the SDK)
• Navigation Targets
• Messages Reference
• Error Handling