Checkout SDK reference

The package exports the Checkout class, error classes, version constant, and TypeScript types used by the public API.

import {
  Checkout,
  VERSION,
  ConfigError,
  MountError,
  type CheckoutConfig,
  type PaymentResult,
  type LynqErrorCode,
} from "@lynqpay/checkout-sdk";

`CheckoutConfig`

Property	Type	Required	Default
`publicKey`	`string`	Yes	—
`clientSecret`	`string`	Yes	—
`environment`	`"production" \| "local"`	No	`production`
`locale`	`string`	No	`en`
`debug`	`boolean`	No	`false`
`labelStyle`	`"floating" \| "fixed"`	No	`floating`

environment selects the hosted Checkout application, not payment test/live mode. Test/live mode is determined by the API keys and Payment Intent. Use local only while developing Lynq’s hosted Checkout application locally.

`new Checkout(config)`

Creates an unmounted browser Checkout instance. It throws ConfigError when publicKey, clientSecret, or environment is invalid, or when constructed outside a browser. At most one Checkout can be mounted on a page at a time.

Lifecycle methods

Method	Returns	Description
`mount(selectorOrElement)`	`this`	Mounts the iframe into a selector or element and begins initialization. Throws `MountError` for an invalid container or lifecycle state.
`unmount()`	`void`	Removes the iframe and resets ready/validation state. The instance remains reusable.
`destroy()`	`void`	Permanently removes the iframe, authentication UI, message handling, and event listeners. Idempotent.
`isMounted()`	`boolean`	Whether this instance currently owns a mounted Checkout iframe.
`isReady()`	`boolean`	Whether hosted Checkout completed initialization.
`isValid()`	`boolean`	Latest hosted-form `canSubmit` state. UI state only.

Subscription methods

Method	Payload
`onReady(handler)`	`ReadyEvent`
`onValidation(handler)`	`ValidationState`
`onPaymentResult(handler)`	`PaymentResult`
`onCheckoutError(handler)`	`LynqError`
`on(event, handler)`	Payload selected from `EventMap` by event name
`off(event, handler?)`	Removes one handler or all handlers for the event

Every on... method returns this for chaining.

Event payloads

`ReadyEvent`

Field	Type	Meaning
`height`	`number`	Initial iframe content height in CSS pixels.

`ValidationState`

Field	Type	Meaning
`canSubmit`	`boolean`	Whether the hosted form considers its current values submittable.
`fields.name`	`boolean`	Cardholder name validity.
`fields.number`	`boolean`	Card number validity.
`fields.exp`	`boolean`	Expiry validity.
`fields.cvv`	`boolean`	Security-code validity.
`fields.brand`	`CardBrand`	Detected card brand or `unknown`.

`PaymentResult`

PaymentResult is a discriminated union on status:

succeeded: includes paymentIntentId and optional paymentMethod
processing: includes paymentIntentId and optional paymentMethod
requires_payment_method: includes paymentIntentId, error, and optional paymentMethod

PaymentError contains a machine-readable code and display-safe message.

Payment-method summaries

Card results may include brand, last4, expMonth, expYear, and cardholderName. Idram results identify the Idram provider. These summaries do not contain the full card number or security code.

Error classes

LynqError: base error with code, message, and retryable
ConfigError: invalid constructor configuration or non-browser construction
MountError: invalid mount container or Checkout lifecycle state

See Errors and troubleshooting for every LynqErrorCode and recommended handling.

`VERSION`

VERSION is the SDK package version string. It is useful in diagnostics when reporting an integration problem.

Start here

Payment methods

Build your integration

Test and go live

Reference

Resources

`CheckoutConfig`

`new Checkout(config)`

Lifecycle methods

Subscription methods

Event payloads

`ReadyEvent`

`ValidationState`

`PaymentResult`

Payment-method summaries

Error classes

`VERSION`

​CheckoutConfig

​new Checkout(config)

​Lifecycle methods

​Subscription methods

​Event payloads

​ReadyEvent

​ValidationState

​PaymentResult

​Payment-method summaries

​Error classes

​VERSION

`CheckoutConfig`

`new Checkout(config)`

Lifecycle methods

Subscription methods

Event payloads

`ReadyEvent`

`ValidationState`

`PaymentResult`

Payment-method summaries

Error classes

`VERSION`