Installation

npm

npm install @lydianpay/sdk-web

import '@lydianpay/sdk-web';

Script tag (CDN)

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@lydianpay/[email protected]/dist/lydian.js"
></script>

Pin a version (e.g. @2.0.0) in production so an upstream release can't change your checkout unexpectedly.

Since v2 the SDK ships as ES modules only: the entry registers window.Lydian and <lydian-checkout> exactly as before, and the heavy wallet SDKs load as separate chunks only when a customer picks that wallet (the CDN serves the chunks alongside the entry). The v1 single-file bundle (dist/lydian.iife.js) no longer exists — if you are upgrading a script tag from v1, change the file name to lydian.js and keep type="module".

Quick start

Place the checkout element where you want the UI, then initialize the SDK:

<lydian-checkout></lydian-checkout>

<script type="module">
  window.Lydian.init({
    dev: false,
    sandbox: false, // both false → production
    publishableKey: 'pk_live_...',
    walletConnectProjectId: 'your-walletconnect-project-id',
    transaction: {
      amount: 2.45,
      currency: 'USD', // 'USD', 'TRY' or 'PHP'
      descriptor: 'Order #1234',
      referenceNumber: 'your-unique-ref',
    },
    paymentSuccessListener: () => {
      window.location.href = '/thank-you';
    },
    paymentFailedListener: (message) => {
      console.error('Payment failed:', message);
    },
    paymentCanceledListener: () => {
      console.log('Payment canceled');
    },
  });
</script>

Configuration

window.Lydian.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 dev 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 (see below). |

flow

Optional per-embed settings. Only settings your Lydian account cannot express live here — everything else is configured once on the merchant portal and applies to every checkout automatically.

| Field | Type | Default | Description | | --------------- | --------- | ------- | ------------------------------------------------------------------------------------------------- | | walletConnect | boolean | false | Offer wallet connection alongside the QR code. Not available from account config. | | assetFirst | boolean | false | Ask the customer to pick the coin before the network, instead of the default network-first order. |

Configured on your Lydian account, not here. They apply to every checkout and there is no per-embed override:

| Setting | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | showApprovalPage | Show the scan-to-pay screen as a confirmation step before asking a connected wallet to sign. Off by default — the wallet opens straight away. | | hideNoWalletOption | Legacy field name retained for compatibility. When true, hides the "Other wallets" option on the wallet selection screen. |

window.Lydian.init({
  // ...
  flow: { walletConnect: true, assetFirst: true },
});

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. |

Updating the transaction

Before the customer pays, you can 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',
});

Environments

| Environment | Flags | | ----------- | ---------------------------- | | Production | dev: false, sandbox: false | | Sandbox | sandbox: true | | Development | dev: true |

Supported assets & networks

USDT, USDC, ETH, PYUSD, RLUSD, USDe, USDS, USDP, DAI across Ethereum, Polygon, Arbitrum, Base, Optimism, Solana, Bitcoin, Celo, Linea, Sonic, Unichain, ZKsync, and more. Which assets appear at checkout is controlled by your Lydian account configuration.

Links

• npm package
• Lydian developer docs

License

MIT