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.

Property	Type	Description
`primary`	string	Primary brand color (overrides dashboard)
`secondary`	string	Secondary brand color (overrides dashboard)

Typography

Property	Type	Description
`h1Font`	string	Font family for H1 headings
`h1FontSize`	string	Font size for H1 headings
`h2Font`	string	Font family for H2 headings
`h2FontSize`	string	Font size for H2 headings
`h3Font`	string	Font family for H3 headings
`h3FontSize`	string	Font size for H3 headings
`bodyFont`	string	Font family for body text
`bodyFontSize`	string	Font size for body text
`customFontUrls`	string[]	URLs to load custom fonts

Buttons

Property	Type	Description
`radius`	string	Border radius for all buttons
`primaryBackground`	string	Background color of primary button
`primaryText`	string	Text color of primary button
`primaryBackgroundHover`	string	Hover background of primary button
`secondaryBackground`	string	Background color of secondary button
`secondaryText`	string	Text color of secondary button
`secondaryBorder`	string	Border color of secondary button
`secondaryBackgroundHover`	string	Hover background of secondary button

Forms

Property	Type	Description
`radius`	string	Border radius for form inputs
`backgroundColor`	string	Background color for default state
`backgroundColorFocus`	string	Background color when input is focused
`textColor`	string	Text color for form inputs
`borderColor`	string	Border color for default state
`borderColorFocus`	string	Border color when input is focused
`labelColor`	string	Color for form labels

Cards

Property	Type	Description
`radius`	string	Border radius for cards
`backgroundColor`	string	Background color for default state
`backgroundColorActive`	string	Background color when card is active/selected
`borderColor`	string	Border color for default state
`borderColorActive`	string	Border color when card is active/selected
`titleColor`	string	Color for card titles
`iconColor`	string	Color 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:

Authentication with the Lemonway API
Creating an account
Starting the onboarding process
Using the returned URL with the widget

8.4 Step‑by‑Step

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;
};

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.

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.

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

Action	Snippet / detail	Outcome
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 widget	See code below	Iframe 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

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

Integration Guide

1. Release Notes & Change Log

⚠️ Important — widget version

1.1 Accessing Widget Versions

Important

2. Overview

2.1 Key features

3. Browser Compatibility

4. Quick‑start

4.1 Add the script

4.2 Add a container

4.3 Initialise the widget

Note

4.4 Destroy the widget instance

4.5 Complete HTML example

5. Configuration Options

5.1 Theme Configuration

Available Options

Colors

Typography

Buttons

Forms

Cards

Example

5.2 Widget Behaviour

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

6.1 React / Next.js

Note

Important

6.2 Vue.js (Vue 3)

6.3 Svelte

7. Trouble Shooting

7.1 Widget Not Displaying

7.2 Styling Issues

Support

8. Obtaining an onboarding URL

8.1 Overview

8.2 Prerequisites

8.3 Integration Process

8.4 Step‑by‑Step

Important

9. Security and Environment

10. Environment Considerations

11. Version Management

11.1 Key Points:

12. End‑to‑End Setup Checklist

Step 1 – Front‑end widget embed

Step 2 – Backend flow to generate onboardingUrl

Step 3 – Wire backend to front‑end

Step 4 – Handle widget events

Step 5 – Test, Secure and Go‑live

Step 2 – Backend flow to generate `onboardingUrl`