Onboarding (KYC/KYB)

This guide explains how to integrate the Footprint onboarding flow for KYC (Know Your Customer) and KYB (Know Your Business) into your JavaScript/TypeScript applications.

The default behavior launches the onboarding flow within a modal. For an inline integration option, see the Inline Integration section below.

1. Start the onboarding:

   • Start the onboarding and get an onboarding token, e.g., obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH, from POST /onboardings.

2. Initialize the Footprint Flow:

   • Trigger Footprint, for example, when a button is clicked. Then, pass the onboardingSessionToken and onComplete callback to the initialize method.

javascript
1import "@onefootprint/footprint-js/dist/footprint-js.css";
2import { onboarding } from "@onefootprint/footprint-js";
3
4const App = () => {
5  const launch = () => {
6    onboarding.initialize({
7      onboardingSessionToken: "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
8      onComplete: (validationToken) => {
9        console.log(validationToken);
10      },
11    });
12  };
13
14  return (
15    <button type="button" onClick={launch}>Launch Footprint</button>
16  );
17}

3. Handle Completion:
   • Once the user completes the flow, you'll receive the validationToken through the onComplete callback. Post this token to your backend for further processing.

Click here to check out a full example.

Footprint provides several events based on actions performed by the user. To listen to events, pass them from either the initialize (modal) or initializeInline method.

typescript
1import { onboarding } from "@onefootprint/footprint-js";
2
3onboarding.initialize({
4  onboardingSessionToken: "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
5  onComplete: (validationToken) => {
6    console.log(validationToken);
7  },
8  onError: (error) => {
9    console.log(error);
10  },
11  onAuth: (validationToken) => {
12    console.log(validationToken);
13  },
14  onCancel: () => {
15    console.log("User canceled the flow");
16  },
17  onClose: () => {
18    console.log("User closed the flow");
19  },
20});

Pass onRequirementChange to track the flow's progress from your page — for example, to drive your own stepper while the flow runs inline. It fires whenever the requirement being executed changes, and again when the flow moves to a different screen within the same requirement:

typescript
1import { onboarding } from "@onefootprint/footprint-js";
2
3onboarding.initializeInline({
4  onboardingSessionToken: "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
5  containerId: "footprint-container",
6  onComplete: (validationToken) => {
7    console.log(validationToken);
8  },
9  onRequirementChange: ({ kind, page }) => {
10    console.log(kind); // e.g. "collect_business_data"
11    console.log(page); // e.g. "business_owners", or undefined
12  },
13});

Possible kind values are collect_business_data, collect_data (personal information), collect_document, liveness (passkey registration), link_bank_account, collect_investor_profile, collect_card_data, collect_custom_data, collect_document_data, confirm_verified_prefill, register_auth_method and process. New kinds may be added over time, so handle unknown values gracefully.

When a requirement spans more than one distinct screen, the payload also carries a page field. Today it is set to business_owners while the beneficial-owners screen of collect_business_data is shown, so a stepper can distinguish it from the business-details screen of the same requirement. It is omitted everywhere else, and new page values may be added over time.

For use cases where you prefer to embed the onboarding flow directly within your page instead of using a modal, you can use the initializeInline method.

Note: The inline integration requires a container element in your DOM where the flow will be rendered.

javascript
1import "@onefootprint/footprint-js/dist/footprint-js.css";
2import { onboarding } from "@onefootprint/footprint-js";
3
4const App = () => {
5  const launchInline = () => {
6    onboarding.initializeInline({
7      onboardingSessionToken: "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
8      containerId: "footprint-container",
9      onComplete: (validationToken) => {
10        console.log(validationToken);
11      },
12    });
13  };
14
15  return (
16    <div>
17      <button type="button" onClick={launchInline}>Launch Footprint Inline</button>
18      <div id="footprint-container" style={{ height: '600px', width: '100%' }}></div>
19    </div>
20  );
21}

The inline integration supports the same event handlers and customization options as the modal version. Make sure to provide adequate height for the container element (recommended minimum: 600px).

You can customize the appearance of the onboarding flow by passing an appearance object to either the initialize (modal) or initializeInline method.

typescript
1import { onboarding } from "@onefootprint/footprint-js";
2
3onboarding.initialize({
4  onboardingSessionToken: "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
5  onComplete: (validationToken) => {
6    console.log(validationToken);
7  },
8  appearance: {
9    variables: {
10      borderRadius: "8px",
11      colorSuccess: "#10b981",
12      colorError: "#F87171",
13      buttonPrimaryBg: "#5550e9",
14    },
15  },
16});

For more information, including a list of available variables, check out the customization guide.