Lemonway Widget to help integrate our Online Onboarding directly on your platform
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://media-onb-prd.s3.eu-west-3.amazonaws.com/widget/lemonway-widget.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.
3.4 Complete HTML example
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Lemonway Onboarding</title>
<script src="https://media-onb-prd.s3.eu-west-3.amazonaws.com/widget/lemonway-widget.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 |
---|---|---|
| string | UI language ( |
| function | Callback function triggered when the user navigates to a different page within the widget. |
| function | Callback function triggered when the user clicks on “My Account”.\ Example pages: Session Expired, Pending Verification, Invalid Link. |
| 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 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 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 theonboardingData
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://media-onb-prd.s3.eu-west-3.amazonaws.com/widget/lemonway-widget.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
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.