Integration Guide

1 .  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.

1.1 Key features

Plug‑and‑play:: add one script tag and a container; no backend changes.
Responsive Design: across and 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).

2. Browser Compatibility

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

Chrome, Firefox, Safari, Edge, Opera

3 . Quick‑start

3.1 Add the script

Add the following script tag to your HTML page:

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

3.2 Add a container

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

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

3.3 Initialise the widget

Initialise the widget by adding the following JavaScript code:

document.addEventListener('DOMContentLoaded', () => {
  LemonwayWidget.init(
    '<YOUR_ONBOARDING_URL>', // Obtained from the reguler 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

3.4 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.1.0.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>

4.  Configuration Options

Option	Type	Description
`lang`	string	UI language (`fr`, `en`, `de`, `it`, `es`). The default language is based on the URL parameter or browser language.
`onPageChange`	function	Callback function triggered when the user navigates to a different page within the widget.
`onMyAccount`	function	Callback function triggered when the user clicks on “My Account”.\ Example pages: Session Expired, Pending Verification, Invalid Link.
`onFinish`	function	Callback function triggered when the onboarding process is completed.

4. 1 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.

5. 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.

5. 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.1.0.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.

5.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.1.0.min.js';
  script.onload = () => {
    window.LemonwayWidget?.init(
      'YOUR_ONBOARDING_URL',
      'lemonway-widget-container',
      { lang: 'en' }
    );
  };
  document.body.appendChild(script);
});
</script>

5.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.1.0.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>

6. Trouble Shooting

6.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.

6.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.

7 .  Obtaining an onboarding URL

7.1 Overview

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

7.2  Prerequisites

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

7.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

7.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 theurl 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 an 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 reguler 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.

8.  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.

9. 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

10. 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.

10.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.

11. 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.1.0.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`

API call (dev)	Purpose	Outcome
`POST /oauth/token`	Obtain OAuth token	`access_token` ready
`POST /accounts/individual`	Create account	Account ID created
`POST /onboardings/individual`	Start onboarding	Response returns `url` (the `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 . Overview

1.1 Key features

2. Browser Compatibility

3 . Quick‑start

3.1 Add the script

3.2 Add a container

3.3 Initialise the widget

Note

3.4 Complete HTML example

4. Configuration Options

4. 1 Widget Behaviour

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

5. 1 React / Next.js

Note

Important

5.2 Vue.js (Vue 3)

5.3 Svelte

6. Trouble Shooting

6.1 Widget Not Displaying

6.2 Styling Issues

Support

7 . Obtaining an onboarding URL

7.1 Overview

7.2 Prerequisites

7.3 Integration Process

7.4 Step‑by‑Step

Important

8. Security and Environment

9. Environment Considerations

10. Version Management

10.1 Key Points:

11. 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

1 .  Overview

3 . Quick‑start

4.  Configuration Options

7 .  Obtaining an onboarding URL

7.2  Prerequisites

7.4  Step‑by‑Step

8.  Security and Environment

Step 2 – Backend flow to generate `onboardingUrl`