API Reference Docs
OnboardingAPI v1ChangelogAPI Status
Start typing to search…

Hosted Online Onboarding

Lemonway Widget to help integrate our Online Onboarding directly on your platform

Integration Guide

1. Release Notes & Change Log



⚠️ Important — widget version

Our examples use a floating patch version:

<script src="https://hosted-onboarding.lemonway.com/widget/0.2.x.min.js"></script>

Before going to production, replace x with the exact patch version listed in the Change Log at the top of this page. For example, if the latest release is 0.2.6:

<script src="https://hosted-onboarding.lemonway.com/widget/0.2.§.min.js"></script>

This ensures predictable behavior and avoids unexpected changes. When a new minor or major version is announced in the Change Log, update the URL accordingly and re-test.

1.1 Accessing Widget Versions

It possible to access specific widget versions using the URL patterns.

Specific version (recommended for production):

https://hosted-onboarding.lemonway.com/widget/{version}.min.js

  • Where {version} is the version number (for example, 1.0.1).

Latest version (always up-to-date): https://hosted-onboarding.lemonway.com/widget/latest.min.js

  • Note, that the URL always points to the most recent version.
❗️

Important

Use with caution in production as updates are automatic.

2. Overview

The Lemonway Hosted Online Onboarding widget embeds Lemonway’s KYC onboarding flow into your web or mobile site through a lightweight iframe. All regulatory pages, media capture, and verifications are hosted by Lemonway; you simply load the widget and pass a unique onboarding URL.

2.1 Key features

  • Plug‑and‑play: add one script tag and a container; no backend changes.
  • Responsive Design: across all devices.
  • Multi‑lingual UI: French (fr), English (en), German (de), Italian (it), Spanish (es).
  • Event callbacks: so your application can track progress (onPageChange, onMyAccount, onFinish).

3. Browser Compatibility

Lemonway Widget is compatible with latest versions of the following browsers:

  • Chrome, Firefox, Safari, Edge, Opera

4. Quick‑start

4.1 Add the script

Add the following script tag to your HTML page:

<script src="https://hosted-onboarding.lemonway.com/widget/0.2.x.min.js"></script>

4.2 Add a container

Add a container element with a unique ID where you want the widget to appear:

<div id="lemonway-widget"></div>

4.3 Initialise the widget

Initialise the widget by adding the following JavaScript code:

document.addEventListener('DOMContentLoaded', () => {
  LemonwayWidget.init(
    '<YOUR_ONBOARDING_URL>', // Obtained from the regular onboarding process.
    'lemonway-widget',      // container ID
    {
      lang: 'en'            // optional: fr, en, de, it, es
    }
  );
});
📘

Note

Replace 'YOUR_ONBOARDING_URL' with the URL of your onboarding process.

See: Obtaining an onboarding URL

See: Onboarding Legal Entities or Onboarding Individuals

4.4 Destroy the widget instance

Use the following method to explicitly destroy an instance attached to a specific container:

LemonwayWidget.destroy(targetId: string): boolean

4.5 Complete HTML example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <title>Lemonway Onboarding</title>
  <script src="https://hosted-onboarding.lemonway.com/widget/0.2.x.min.js"></script>
</head>
<body>
  <h1>Lemonway Onboarding</h1>
  <div id="lemonway-widget"></div>

  <script>
    document.addEventListener('DOMContentLoaded', () => {
      LemonwayWidget.init(
        '<YOUR_ONBOARDING_URL>',
        'lemonway-widget',
        {
          lang: 'en',
          onPageChange: () => console.log('Page changed'),
          onMyAccount:  () => console.log('User opened My Account'),
          onFinish:     () => console.log('Onboarding finished')
        }
      );
    });
  </script>
</body>
</html>

5. Configuration Options

Name Status Type / Values Description
lang Optional
string enum "fr" · "en" · "de" · "it" · "es" default: auto
UI language. Defaults from URL parameter or browser language.
onPageChange Optional
function (page: string) => void
Called when the user navigates to a different page within the widget.
onMyAccount Optional
function () => void
Called when “My Account” is clicked (e.g., Session Expired, Pending Verification, Invalid Link pages).
onFinish Optional
function () => void
Called when the onboarding process completes.
isSidebarMenuEnabled Optional
boolean default: false
Controls whether the sidebar navigation menu is displayed.
isWelcomePageEnabled Optional
boolean default: true
If false, the flow redirects users directly to the validation page (skips welcome pages).
arePersonalInformationsReadonly Optional
boolean default: false
If true, first and last name fields are read-only in personal information forms.

5.1 Theme Configuration

The Lemonway Widget supports theme customization through the theme configuration object.

Available Options

Colors

Global application colors that override those configured in the dashboard. These values can be custmized if you do not want to configure everything.

PropertyTypeDescription
primarystringPrimary brand color (overrides dashboard)
secondarystringSecondary brand color (overrides dashboard)

Typography

PropertyTypeDescription
h1FontstringFont family for H1 headings
h1FontSizestringFont size for H1 headings
h2FontstringFont family for H2 headings
h2FontSizestringFont size for H2 headings
h3FontstringFont family for H3 headings
h3FontSizestringFont size for H3 headings
bodyFontstringFont family for body text
bodyFontSizestringFont size for body text
customFontUrlsstring[]URLs to load custom fonts

Buttons

PropertyTypeDescription
radiusstringBorder radius for all buttons
primaryBackgroundstringBackground color of primary button
primaryTextstringText color of primary button
primaryBackgroundHoverstringHover background of primary button
secondaryBackgroundstringBackground color of secondary button
secondaryTextstringText color of secondary button
secondaryBorderstringBorder color of secondary button
secondaryBackgroundHoverstringHover background of secondary button

Forms

PropertyTypeDescription
radiusstringBorder radius for form inputs
backgroundColorstringBackground color for default state
backgroundColorFocusstringBackground color when input is focused
textColorstringText color for form inputs
borderColorstringBorder color for default state
borderColorFocusstringBorder color when input is focused
labelColorstringColor for form labels

Cards

PropertyTypeDescription
radiusstringBorder radius for cards
backgroundColorstringBackground color for default state
backgroundColorActivestringBackground color when card is active/selected
borderColorstringBorder color for default state
borderColorActivestringBorder color when card is active/selected
titleColorstringColor for card titles
iconColorstringColor for card icons

Example

LemonwayWidget.init('YOUR_ONBOARDING_URL', 'lemonway-widget-container', {
  lang: 'fr',
  isSidebarMenuEnabled: true,
  theme: {
    typography: {
      h1Font: 'Lato, sans-serif',
      h1FontSize: '1.5rem',
      h2Font: 'Lato, sans-serif',
      h2FontSize: '1.25rem',
      h3Font: 'Lato, sans-serif',
      h3FontSize: '1.25rem',
      bodyFont: 'Lato, sans-serif',
      bodyFontSize: '0.875rem'
    },
    buttons: {
      radius: '0.5rem',
      primaryBackground: '#0066CC',
      primaryText: '#FFFFFF',
      primaryBackgroundHover: '#0052A3',
      secondaryBackground: '#FFFFFF',
      secondaryText: '#0066CC',
      secondaryBorder: '#0066CC',
      secondaryBackgroundHover: '#F0F7FF'
    },
    colors: {
      primary: '#0066CC',
      secondary: '#FF6600'
    },
    forms: {
      radius: '0.75rem',
      backgroundColor: '#FFFFFF',
      backgroundColorFocus: '#FAFAFA',
      textColor: '#333333',
      borderColor: '#E0E0E0',
      borderColorFocus: '#3643BA',
      labelColor: '#333333'
    },
    cards: {
      radius: '0.75rem',
      backgroundColor: '#FFFFFF',
      backgroundColorActive: '#F0F1FC',
      borderColor: '#E0E0E0',
      borderColorActive: '#3643BA',
      titleColor: '#333333',
      iconColor: '#666666'
    }
  }
});

5.2 Widget Behaviour

  • The widget automatically adjusts its height based on the content.
  • The minimum height is 800px.
  • For security verification screens, additional padding is applied.

6. Using the Widget in React, Next.js, Vue, or Svelte

The Lemonway widget can also be easily integrated into modern JavaScript frameworks such as React, Next.js, Vue, or Svelte, since it is based on a simple script and iframe setup.

6.1 React / Next.js

"use client" // for next.js

import { useEffect } from 'react';

const OnboardingWidget = () => {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://hosted-onboarding.lemonway.com/widget/0.2.x.min.js';
    script.onload = () => {
      window.LemonwayWidget?.init(
        'YOUR_ONBOARDING_URL',
        'lemonway-widget-container',
        {
          lang: 'en'
        }
      );
    };
    document.body.appendChild(script);
  }, []);

  return <div id="lemonway-widget-container"></div>;
};

export default OnboardingWidget;
📘

Note

This same logic applies to Next.js (in a Client Component), Vue (in mounted()), or Svelte (in onMount()).

👍

Important

Ensure that the script is only loaded once and that the DOM container is present before initialising the widget.

6.2 Vue.js (Vue 3)

In a view component.

<template>
  <div id="lemonway-widget-container"></div>
</template>

<script setup>
import { onMounted } from 'vue';

onMounted(() => {
  const script = document.createElement('script');
  script.src = 'https://hosted-onboarding.lemonway.com/widget/0.2.x.min.js';
  script.onload = () => {
    window.LemonwayWidget?.init(
      'YOUR_ONBOARDING_URL',
      'lemonway-widget-container',
      { lang: 'en' }
    );
  };
  document.body.appendChild(script);
});
</script>

6.3 Svelte

In a Svelte component:

<script>
  import { onMount } from 'svelte';

  onMount(() => {
    const script = document.createElement('script');
    script.src = 'https://hosted-onboarding.lemonway.com/widget/0.2.x.min.js';
    script.onload = () => {
      window.LemonwayWidget?.init(
        'YOUR_ONBOARDING_URL',
        'lemonway-widget-container',
        { lang: 'en' }
      );
    };
    document.body.appendChild(script);
  });
</script>

<div id="lemonway-widget-container"></div>

7. Trouble Shooting

7.1 Widget Not Displaying

  • Verify that the container element exists in the DOM before initialising the widget.
  • Check browser console for any JavaScript errors.
  • Ensure the onboarding URL is correct and accessible.

7.2 Styling Issues

The widget is designed to be responsive and will adapt to the width of its container. If you experience styling issues:

  • Ensure the container has a defined width (percentage or pixels).
  • Avoid applying CSS that might conflict with the iframe's styling.
👍

Support

For any technical issues or questions regarding the widget integration, please contact Lemonway support.

8. Obtaining an onboarding URL

8.1 Overview

This guide explains how to obtain the onboarding URL required for integrating the Lemonway Widget into your website.

8.2 Prerequisites

  • Lemonway account with API credentials.
  • API credentials (API key, OAuth token).
  • Access to the Lemonway API endpoints.

8.3 Integration Process

The typical integration process involves:

  1. Authentication with the Lemonway API
  2. Creating an account
  3. Starting the onboarding process
  4. Using the returned URL with the widget

8.4 Step‑by‑Step

  1. Authenticate with Lemonway API to obtain an OAuth token:

    // Example using fetch API
const getOAuthToken = async () => {
  const formData = new URLSearchParams();
  formData.append('Grant_type', 'client_credentials');

  const response = await fetch('https://ls.dev.lemonway.com:4431/oauth/api/v1/oauth/token', {
    method: 'POST',
    headers: {
      Authorization: 'basic YOUR_OAUTH_TOKEN',
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: formData
  });

  const data = await response.json();
  return data.access_token;
};

  2. Create the individual account:

    // Example using fetch API
const createIndividualAccount = async (token, accountData) => {
  const response = await fetch('https://onboarding-api.lemonway.com/accounts/individual', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(accountData)
  });

  return await response.json();
};

    The accountData object should contain the necessary information about the individual account according to the Lemonway API documentation.

  3. Start the onboarding to retrieve the url field:

    // Example using fetch API
const startIndividualOnboarding = async (token, onboardingData) => {
  const response = await fetch('https://onboarding-api.lemonway.com/onboardings/individual', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(onboardingData)
  });

  const data = await response.json();
  return data.url; // This is your onboarding URL that you will add in the LemonwayWidget.init
};

    The onboardingData object should contain the necessary details for the onboarding process according to the Lemonway API documentation.

  4. The response from the previous step will include a url field. This is the onboarding URL you'll use with the Lemonway Widget:

    document.addEventListener('DOMContentLoaded', () => {
  LemonwayWidget.init(
    '<YOUR_ONBOARDING_URL>', // Obtained from the regular onboarding process.
    'lemonway-widget',      // container ID
    {
      lang: 'en'            // optional: fr, en, de, it, es
    }
  );
});

❗️

Important

The redirectUrl field in the onboardingData object is required, even though it isn't used by the embedded widget. You can enter any valid URL—your website’s homepage, for example. This field is only relevant for the web-based onboarding flow and is ignored when using the widget.

9. Security and Environment

  • Never embed API keys or OAuth tokens in client side code.
  • Use HTTPS for all API calls and for serving the widget page.

10. Environment Considerations

  • For development and testing, use the development environment URLs provided in this guide.
  • For production, replace the development URLs with production URLs provided by Lemonway.

11. Version Management

The Lemonway Hosted Online Onboarding widget is versioned to ensure stability and predictability in your integrations. Each release is associated with a specific version number, which is included in the script URL you embed on your site.

11.1 Key Points:

  • No automatic updates: Once a version is released, it is never modified retroactively. This ensures that your implementation will not break due to unexpected changes.
  • Manual upgrades: If a new version is published, you will need to manually update the script URL to use it.

12. End‑to‑End Setup Checklist

Step 1 – Front‑end widget embed

ActionSnippet / detailOutcome
Add the widget script<script src="https://hosted-onboarding.lemonway.com/widget/0.2.x.min.js"></script>Browser downloads the widget bundle
Create the container<div id="lemonway-widget-container"></div>Placeholder exists for the iframe
Initialise the widgetSee code belowIframe shows first KYC screen
LemonwayWidget.init(
  onboardingUrl,
  'lemonway-widget-container',
  { lang: 'en' }
);

Step 2 – Backend flow to generate onboardingUrl

Operation Endpoint Description & Outcome
Obtain OAuth token
POST /oauth/token

Exchange client credentials for an access token (dev).

Outcome: access_token ready
Create account
POST /accounts/individual

Provision a new individual account.

Outcome: Account ID created
Start onboarding
POST /onboardings/individual

Initiate the onboarding flow for the created account.

Outcome: Response returns url (onboardingUrl)

Step 3 – Wire backend to front‑end

Pass url from step 2 into the widget initialiser.

Step 4 – Handle widget events

LemonwayWidget.init(onboardingUrl, 'lemonway-widget-container', {
  lang: 'en',
  onPageChange: page => console.log('Moved to', page),
  onMyAccount:  ()   => console.log('User opened My Account'),
  onFinish:     ()   => markUserAsVerified()
});

Step 5 – Test, Secure and Go‑live

  1. Use dev endpoints until the flow works end‑to‑end.
  2. Switch to production endpoints.
  3. Keep all API calls on the server; expose only onboardingUrl.
  4. Serve every page over HTTPS.