Web SDK

The Lydian Web SDK (@lydianpay/sdk-web) is a drop-in checkout for the browser. It registers a <lydian-checkout> custom element and a global window.Lydian API that walks your customer through paying with a connected wallet or QR code.

This page is the library reference. For a step-by-step walkthrough, see Web Checkout; to decide between hosted and embedded checkout, see Choose Your Integration.

Installation

Install from npm, or load the pinned build from a CDN. Pin a version so an upstream release can't change your checkout unexpectedly.

npm install @lydianpay/sdk-web

With a bundler, import the package once to register the element and the global:

import '@lydianpay/sdk-web'

The SDK ships as ES modules, so a script-tag include must use type="module".

Add the checkout element

Place the <lydian-checkout> element where the checkout should render. It stays hidden until you initialize the SDK.

<lydian-checkout></lydian-checkout>

Initialize the SDK

Call window.Lydian.init(options) to render the checkout and start a payment.

window.Lydian.init({
  sandbox: true,
  dev: false,
  isEmbedded: true,
  publishableKey: '{PUBLISHABLE_KEY}',
  walletConnectProjectId: 'your-walletconnect-project-id',
  transaction: {
    amount: 2.45,
    currency: 'USD',
    descriptor: 'Order #1234',
    referenceNumber: 'your-unique-ref',
  },
  paymentSuccessListener: () => {},
  paymentFailedListener: (message) => {},
  paymentCanceledListener: () => {},
})

`init` options

Option	Type	Required	Description
`publishableKey`	`string`	yes	Your Lydian publishable key (`pk_...`).
`walletConnectProjectId`	`string`	yes	Your WalletConnect (Reown) project ID, used to power wallet connections.
`transaction`	`Transaction`	yes	The payment to collect (see below).
`dev`	`boolean`	yes	Target the development environment.
`sandbox`	`boolean`	yes	Target sandbox. With both `dev` and `sandbox` `false`, the SDK uses production.
`paymentSuccessListener`	`() => void`	yes	Called when the payment completes.
`paymentFailedListener`	`(message: string) => void`	yes	Called on failure, with a message.
`paymentCanceledListener`	`() => void`	yes	Called when the customer cancels.
`isEmbedded`	`boolean`	no	Render the checkout inline (embedded) instead of as a modal.
`flow`	`InitFlowOptions`	no	Per-embed flow overrides, e.g. `{ walletConnect: true }` to offer wallet connection alongside the QR code.

`Transaction`

Field	Type	Required	Description
`amount`	`number`	yes	Amount to charge.
`currency`	`'USD' \| 'TRY' \| 'PHP'`	yes	Fiat currency the amount is denominated in.
`referenceNumber`	`string`	yes	Your unique reference for this payment.
`descriptor`	`string`	no	Human-readable description shown to the customer.

Environments

Environment	Flags
Production	`dev: false, sandbox: false`
Sandbox	`sandbox: true`
Development	`dev: true`

Updating the transaction

Before the customer pays, update the amount or currency. This also resets the checkout UI to its initial state.

window.Lydian.updateTransaction({
  amount: 1.45,
  currency: 'USD',
  descriptor: 'Order #1234',
  referenceNumber: 'your-unique-ref',
})

Listeners

Provide these callbacks in init to react to the payment outcome:

paymentSuccessListener() — the payment completed.
paymentFailedListener(message) — the payment failed; message describes why.
paymentCanceledListener() — the customer cancelled.

Supported assets & networks

Which assets appear at checkout is controlled by your Lydian account configuration; the SDK renders whatever your account has enabled across the supported networks.

Web Checkout — step-by-step embedding guide.
Accept Your First Payment — the hosted-checkout alternative.
API Reference: Sessions · Transactions.