Lightspeed Online Payments SDK

@lightspeed/online-payments-sdk is a browser SDK for displaying Lightspeed Payments widgets in your web application.

This is intended for partners who wish to add payments functionality to an integration with a Lightspeed product.

For onboarding questions, account configuration, or production enablement: contact your Lightspeed representative.

Installation

npm install @lightspeed/online-payments-sdk

Requirements

• A browser environment with window and document
• A payment session obtained from your Lightspeed Payments integration
• An HTML element where the payment widget can be mounted

Quick start

Add a mount element to your page:

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

Mount the widget with the payment session from your integration:

import {LightspeedPayments} from '@lightspeed/online-payments-sdk';
import '@lightspeed/online-payments-sdk/styles/lightspeed-global-styles.css';

const mountPoint = document.getElementById('payment-widget');

if (!mountPoint) {
  throw new Error('Payment widget mount point was not found');
}

const controller = await LightspeedPayments.v1.mountPaymentWidget(session, {
  mountPoint,
});

Keep the returned controller to submit the widget or remove it when the containing page or component is no longer needed.

Configuration

mountPaymentWidget(session, configuration) accepts a payment session and the following configuration:

| Option | Description | | --------------- | ---------------------------------------------------------------- | | mountPoint | Required HTMLElement where the SDK renders the payment widget. | | defaultValues | Optional initial address values: country and postalCode. | | listeners | Optional callbacks for widget lifecycle and payment events. | | theme | Optional visual theme: dark. |

const controller = await LightspeedPayments.v1.mountPaymentWidget(session, {
  mountPoint,
  defaultValues: {
    country: 'CA',
    postalCode: 'H1H1H1',
  },
  listeners: {
    onReady: () => {
      // The widget is ready for payer input.
    },
    onChange: event => {
      submitButton.disabled = event.code !== 'Complete';
    },
    onSucceeded: () => {
      // Continue after a successful payment or payment-method save.
    },
    onDeclined: event => {
      // Show a decline message appropriate for event.code.
    },
    onError: event => {
      // Handle a widget or processing error.
    },
  },
});

Events

Listeners receive an event with a status and code. Available listener names are onReady, onChange, onSucceeded, onPending, onDeclined, and onError.

| Status | Codes | | ----------- | -------------------------------------------------------------------------------------------------------------- | | Ready | Ready | | Change | Complete, Incomplete | | Succeeded | Authorized | | Pending | Processing | | Declined | CardValidation, Generic, PaymentMethodNotSupported | | Error | Unexpected, InvalidSession, InvalidSessionPayload, UnsupportedLocation, Processing, FormValidation |

Submit and unmount

Call submit() in response to your application's payment action. Call unmount() before removing or replacing the mount element.

submitButton.addEventListener('click', async () => {
  await controller.submit();
});

// For example, during page or component cleanup.
controller.unmount();

submit() returns Promise<WidgetSubmitResult>. Existing intent-bound Stripe and Adyen sessions retain their runtime behavior, but TypeScript integrations that explicitly treat the submit result as Event must first handle or exclude the new RequiresFinalization status. Listener callbacks are unchanged and continue to receive only Event.

Deferred MOTO payments

Deferred Stripe moto and moto-with-save sessions return a RequiresFinalization result for backend finalization instead of reporting payment success. Integrations opting into this mode must forward the returned artifact unchanged and handle definitive declines through reportFinalizationDecline.

The complete deferred Stripe MOTO integration guide is maintained in the GitHub repository and is not included in the npm package.

Theming

Use theme to select a widget appearance:

• Omit theme to use the default appearance.
• dark uses a dark appearance and styles the mount element with a dark background.

Custom themes can be used with support from the Lightspeed Payments team.

await LightspeedPayments.v1.mountPaymentWidget(session, {
  mountPoint,
  theme: 'dark',
});

For a wrapper around a widget using the dark theme, use THEME_COLORS to match the SDK's dark container colors:

import {THEME_COLORS} from '@lightspeed/online-payments-sdk';

wrapper.style.backgroundColor = THEME_COLORS.DARK.BACKGROUND;
wrapper.style.color = THEME_COLORS.DARK.TEXT;

Checking the SDK version

The running SDK version is available at runtime, matching the version published to npm:

import {LightspeedPayments, SDK_VERSION} from '@lightspeed/online-payments-sdk';

console.log(LightspeedPayments.version); // e.g. "1.8.0"
console.log(SDK_VERSION); // e.g. "1.8.0"

While a widget is mounted, its mount element also carries a data-lightspeed-payments-sdk-version attribute, so the running version can be inspected directly in browser devtools without any application code:

<div id="payment-widget" data-lightspeed-payments-sdk-version="1.8.0"></div>

The attribute is removed when controller.unmount() is called.