SDK Buddle - Integration and SSR

The SDK is available in three different formats: ESM, IIFE, and UMD.

📘
Note
Lemonway does not own and is not resposible for the content or maintanance of external websites listed on this page.

SDK Formats

ESM (EcmaScript Module)

The standard format can be called from HTML directly in most modern web browsers.

<script type="module">
    import LwHostedFields from 'hosted-fields-sdk';
    const hostedFields = new LwHostedFields(config);
</script>

The ESM format has a larger file size, but has several benefits:

Can be bundled with your application using tools that support tree-shaking (for example, Rollup or Webpack).
Can be used for Server-Side Rendering (SSR).
Can be lazy-loaded (SDK is not loaded until the user navigates to the payment page).

Sandbox Example:

let LwHostedFields = (await import("https://sandbox-webkit.lemonway.fr/hosted-fields/sdk/@lw/hosted-fields-sdk-2.0.0.iife.js")).default

ESM via npm package (recommended)

You can also integrate the SDK as an npm dependency in front-end projects such as React, Vue, Svelte, Next.js, and Nuxt.

For the latest stable version, installation details, and package metadata, refer to the official npm page: @lemonway/hosted-fields-sdk.

Install:

npm install @lemonway/hosted-fields-sdk

pnpm add @lemonway/hosted-fields-sdk

yarn add @lemonway/hosted-fields-sdk

If needed, you can pin a major version to avoid unexpected breaking changes during upgrades:

npm install @lemonway/hosted-fields-sdk@3

⚠️
Warning
iframeUrl is required with this integration method
When the SDK is loaded from npm (or from a CDN such as unpkg/jsdelivr), it cannot auto-discover the location of the Lemonway iframe application - auto-discovery only works when the SDK and the iframe are served side-by-side from the same Lemonway domain. You must explicitly set the iframeUrl option, otherwise mount() will fail to load the iframe.
The iframeUrl must include the same version number as the @lemonway/hosted-fields-sdk package you installed (e.g. if you installed version 3.0.0, the URL must contain 3.0.0). Installing a different SDK version later requires updating this URL accordingly.

Client-side usage:

import LwHostedFields from "@lemonway/hosted-fields-sdk"; // e.g. version 3.0.0

// Sandbox
const hostedFields = new LwHostedFields({
  ...config,
  iframeUrl: "https://sandbox-webkit.lemonway.fr/hosted-fields-2/3.0.0/iframe/index.html",
});

// Production
const hostedFields = new LwHostedFields({
  ...config,
  iframeUrl: "https://webkit.lemonway.fr/hosted-fields-2/3.0.0/iframe/index.html",
});

hostedFields.mount();

📘
Note
When using SSR, initialize the SDK only in the browser (for example inside a client lifecycle hook), not during server rendering.

Example with dynamic import:

let LwHostedFields;
if (typeof window !== "undefined") {
  LwHostedFields = (await import("@lemonway/hosted-fields-sdk")).default;
}

IIFE (Immediately Invoked Function Expression)

This format is suitable for adding a <script> tag in your HTML. The SDK will be loaded immediately into the LwHostedField namespace.

<script src="https://sandbox-webkit.lemonway.fr/hosted-fields/sdk/@lw/hosted-fields-sdk-2.0.0.iife.js" integrity="sha384-HE1ZALjbEZrCWdWTvn/y8j5sIGJbGql/Aa8iXwQrDdNwOFTigxLgBxJv5Qd0H7/K" crossorigin="anonymous"></script>
<script>
    const hostedFields = new LwHostedFields(config);
</script>

UMD (Universal Module Definition)

The format works for both front-end and back-end. Usually used as a fallback for the IIFE format.

<script src="https://sandbox-webkit.lemonway.fr/hosted-fields/sdk/@lw/hosted-fields-sdk-2.0.0.iife.js"></script>
<script>
    const hostedFields = new LwHostedFields(config);
</script>