Lightspeed Online Payments SDK

@lightspeed/online-payments-sdk is a browser SDK for mounting Lightspeed Payments widgets (Stripe and Adyen) in web applications.

Installation

npm install @lightspeed/online-payments-sdk

Quick start

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

const controller = await LightspeedPayments.v1.mountPaymentWidget(sessionToken, {
  mountPoint: document.getElementById('payment-widget')!,
});

controller.unmount();

Compatibility

• TypeScript/JavaScript
• Browser runtime (requires window)

Theming

The SDK supports custom themes. If no theme is specified, Stripe defaults are used.

Available themes

• default (no theme value)
• invoicing
• dark

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

await LightspeedPayments.v1.mountPaymentWidget(paymentSession, {
  mountPoint: document.getElementById('payment-widget')!,
  theme: 'dark',
});

Container styling

For dark mode, the SDK styles the mount element you pass in mountPoint. If you style a parent wrapper, use THEME_COLORS.

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

Documentation

• Datadog logging reference: packages/lsp-online-payments-sdk/docs/DATADOG_LOGGING.md
• Sandbox releases (testing unreleased builds in a real app): packages/lsp-online-payments-sdk/docs/sandbox-releases.md

Development

Run SDK checks (same order as CI):

npm run lint --workspace @lightspeed/online-payments-sdk
npm run typecheck --workspace @lightspeed/online-payments-sdk
npm run test --workspace @lightspeed/online-payments-sdk

Build package:

npm run build --workspace @lightspeed/online-payments-sdk

Inspect publish contents:

npm pack --dry-run

Publishing and release flow

Publishing is handled by CircleCI (not manual local publish).

• Release path runs on main and release/*.
• CircleCI runs quality gates (lint, typecheck, unit tests, build, e2e).
• verify_package_version compares local package.json version with npm.
• If local version is not higher, publish is skipped.
• If local version is higher, the workflow pauses at manual approval (pause_workflow).
• A human must approve before the release job runs npm publish.

In practice: bump version in packages/lsp-online-payments-sdk/package.json, merge to main, then approve the release hold in CircleCI.

Sandbox releases

To test unreleased SDK changes inside a real app without touching the production package on public npm, publish a sandbox build to GitHub Packages: push a sandbox/* branch and approve the hold_sandbox step in CircleCI. Consuming an app requires no import changes — just an .npmrc scope + a package.json alias. See docs/sandbox-releases.md for the full publish and consume steps.