Lynq.js 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 CheckoutAppearance,
  type PaymentResult,
  type LynqErrorCode,
} from "@lynqpay/js";

`CheckoutConfig`

Property	Type	Required	Default
`publicKey`	`string`	Yes	—
`clientSecret`	`string`	Yes	—
`locale`	`string`	No	`en`
`appearance`	`CheckoutAppearance`	No	—

Test or live mode follows the publishable key. With a pk_test_… key the SDK writes diagnostics to the browser console; with a pk_live_… key it writes nothing. appearance fields are listed under Customize the appearance. locale is a hint forwarded to hosted Checkout.

`new Checkout(config)`

Creates an unmounted browser Checkout instance. It throws ConfigError when publicKey or clientSecret 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. Pass the original handler to off to remove one listener, or omit it to remove every listener for that event. destroy() clears all listeners. onValidation describes the form, not the payment: neither it nor isReady() and isValid() confirms that a payment completed.

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

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