Checkout SDK

@lynqpay/checkout-sdk embeds the Lynq-hosted payment form in your page. Your application controls where Checkout appears and how the surrounding page responds; Lynq controls the payment form, authentication, redirects, and its height.

npm installation

npm install @lynqpay/checkout-sdk

The npm package is ESM-only and includes TypeScript declarations and API documentation for editor autocomplete.

import { Checkout, type PaymentResult } from "@lynqpay/checkout-sdk";

Script-tag installation

If you do not use a bundler, load the IIFE bundle with a classic script tag. Pin the exact released version so an unrelated future release cannot change production checkout without your deployment.

<script src="https://unpkg.com/@lynqpay/checkout-sdk@1.0.0/dist/lynq.js"></script>

The classic script exposes window.Lynq.

<div id="lynq-checkout"></div>
<script src="https://unpkg.com/@lynqpay/checkout-sdk@1.0.0/dist/lynq.js"></script>
<script>
  const checkout = new Lynq.Checkout({
    publicKey: "pk_test_...",
    clientSecret: paymentIntent.clientSecret,
  });

  checkout.onPaymentResult(handlePaymentResult);
  checkout.mount("#lynq-checkout");
</script>

Do not use a floating URL such as @latest in production.

Create Checkout

Create one instance after your server returns a Payment Intent client secret.

const checkout = new Checkout({
  publicKey: "pk_test_...",
  clientSecret: paymentIntent.clientSecret,
  locale: "en",
  labelStyle: "floating",
});

Option	Required	Default	Description
`publicKey`	Yes	—	Browser-safe key from the same test/live environment as the Payment Intent.
`clientSecret`	Yes	—	Checkout credential returned when your server creates the Payment Intent.
`environment`	No	`production`	Hosted application target. Use `local` only while developing Lynq Checkout itself.
`locale`	No	`en`	Locale hint forwarded to hosted Checkout. Use a locale supported by Checkout.
`debug`	No	`false`	Writes SDK diagnostics to the browser console. Keep it disabled in production unless diagnosing an issue.
`labelStyle`	No	`floating`	Use `floating` for in-field labels or `fixed` for labels above inputs.

Mount Checkout

The mount target may be a CSS selector or an HTMLElement.

checkout
  .onReady(() => hideLoadingPlaceholder())
  .onPaymentResult(handlePaymentResult)
  .onCheckoutError(handleCheckoutError)
  .mount("#lynq-checkout");

Mounting inserts an iframe and starts a handshake with hosted Checkout. onReady fires when the form is visible and ready for customer input. Checkout automatically resizes the iframe as its hosted content changes. Do not set the iframe height or listen for internal messages yourself.

Lifecycle and cleanup

Method	When to use it
`mount()`	Insert Checkout and start initialization.
`unmount()`	Temporarily remove Checkout while keeping the instance reusable.
`destroy()`	Permanently remove Checkout, authentication UI, and all SDK listeners.
`isMounted()`	Check whether this instance currently owns the mounted checkout.
`isReady()`	Check whether initialization completed.
`isValid()`	Read the current hosted-form validation state for surrounding UI.

Only one Lynq Checkout may be mounted on a page at once. Call destroy() when a component unmounts or the customer leaves the payment step. Create a new instance for the next Payment Intent.

isReady() and isValid() describe UI state. Neither confirms that a payment completed.

Layout and accessibility

Give the mount container enough width for your checkout layout; the iframe height is managed automatically.
Keep a visible page heading that identifies the payment step.
Show a loading placeholder until onReady fires.
Display onCheckoutError messages in an accessible alert region.
Do not place a second interactive payment form over the Checkout iframe.

Server-rendered applications

The package can be imported by an SSR application, but Checkout can only be constructed in a browser. Constructing it while window or document is unavailable throws ConfigError. For React, construct Checkout inside an effect or client-only component and destroy it in the cleanup function:

useEffect(() => {
  const checkout = new Checkout({ publicKey, clientSecret });
  checkout.onPaymentResult(onPaymentResult).mount(containerRef.current!);

  return () => checkout.destroy();
}, [publicKey, clientSecret, onPaymentResult]);

Make clientSecret stable for the lifetime of that component. If it changes, destroy the old instance before creating a new one. Next, implement Checkout events and outcomes.

Start here

Payment methods

Build your integration

Test and go live

Reference

Resources

npm installation

Script-tag installation

Create Checkout

Mount Checkout

Lifecycle and cleanup

Layout and accessibility

Server-rendered applications

​npm installation

​Script-tag installation

​Create Checkout

​Mount Checkout

​Lifecycle and cleanup

​Layout and accessibility

​Server-rendered applications

npm installation

Script-tag installation

Create Checkout

Mount Checkout

Lifecycle and cleanup

Layout and accessibility

Server-rendered applications