Lynq.js

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

Install

npm install @lynqpay/js

The package is ESM-only and includes TypeScript declarations.

Script-tag installation

Without a bundler, load the IIFE bundle with a classic script tag. It exposes window.Lynq.

<div id="lynq-checkout"></div>

<script
  src="https://unpkg.com/@lynqpay/js@2.0.1/dist/lynq.js"
  integrity="sha384-6nqFwZV/TFc29mZ1s7apfmaZB1Ex2gxUxNgrFsTgvdEzoGjbDNaPJ91JEgFvGSyS"
  crossorigin="anonymous"
></script>
<script>
  const checkout = new Lynq.Checkout({
    publicKey: "pk_test_...",
    clientSecret: paymentIntent.clientSecret,
  });

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

Pin the exact version, never @latest, so a new release cannot change your production checkout. Keep the integrity attribute: the browser refuses to run the file if the CDN serves anything other than the published release. Each version has its own hash, listed in the release notes.

Mount Checkout

Create one instance after your server returns a Payment Intent client secret. Register handlers before mount() so you cannot miss an early event.

import { Checkout } from "@lynqpay/js";

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

checkout
  .onReady(() => hideCheckoutSkeleton())
  .onPaymentResult((result) => {
    if (result.status === "succeeded") {
      showSubmitted(result.paymentIntentId);
      return;
    }

    if (result.status === "processing") {
      showPending(result.paymentIntentId);
      return;
    }

    showPaymentError(result.error.message);
  })
  .onCheckoutError((error) => {
    showCheckoutError(error.message, { canRetry: error.retryable });
  })
  .mount("#lynq-checkout");

The mount target is a CSS selector or an HTMLElement. Checkout inserts an iframe and resizes it as its content changes, so do not set its height yourself.

Handle events

Handler	When it fires	Use it to
`onReady`	The form is visible and accepts input.	Remove your loading placeholder.
`onValidation`	The card form’s state changes.	React to whether the form can submit, or to the detected card brand.
`onPaymentResult`	A payment attempt finished.	Update the customer-facing page.
`onCheckoutError`	Checkout failed to load or initialize.	Show the message and offer a retry when `error.retryable` is true.

Payment results

Result	Show the customer	On your server
`succeeded`	Payment was submitted successfully.	Wait for the verified webhook before fulfilment.
`processing`	A pending state; they do not need to pay again.	Leave the order pending and wait for the webhook.
`requires_payment_method`	`result.error.message`, and let them correct or replace the method.	Do not mark the order paid.

A declined payment is a result, not a Checkout error. Authentication challenges and wallet redirects happen inside Checkout and never appear as results. See the Lynq.js reference for exact payloads and Errors for each error code.

Customize the appearance

Match Checkout to your site with appearance. Every field is optional; unset fields keep the theme’s own value.

const checkout = new Checkout({
  publicKey: "pk_test_...",
  clientSecret: paymentIntent.clientSecret,
  appearance: {
    theme: "dark",
    labels: "floating",
    colorPrimary: "#c6f432",
    borderRadius: "6px",
  },
});

Field	Default	Description
`theme`	`light`	`light` or `dark` base palette. The colours below apply on top of it.
`labels`	`above`	`above` keeps labels above the fields; `floating` shows them inside the fields and moves them up as the customer types.
`colorPrimary`	Theme	Pay button, focus rings, and the selected payment method. The button text switches between black and white to stay readable.
`colorBackground`	Theme	Background of the fields and the payment-method list.
`colorText`	Theme	Text and labels. Secondary text is derived from it.
`colorBorder`	Theme	Borders around and between fields.
`colorDanger`	Theme	Error messages and invalid fields.
`borderRadius`	`8px`	Corner radius in whole pixels, from `0px` to `99px`.

Colours must be hex values such as #2563eb or #26e. An invalid or unknown entry never stops Checkout: it is ignored and the theme’s own value applies. With a pk_test_… key the SDK logs a console warning saying why.

Clean up

Only one Checkout may be mounted on a page at once. Call destroy() when the customer leaves the payment step, and create a new instance for the next Payment Intent. unmount() removes Checkout but keeps the instance reusable.

Server-rendered applications

The package can be imported during server rendering, but Checkout can only be constructed in a browser; anywhere else it throws ConfigError. In React, construct it inside an effect 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]);

Keep clientSecret stable for the lifetime of that component.

Start here

Payment methods

Build your integration

Test and go live

Reference

Install

Script-tag installation

Mount Checkout

Handle events

Payment results

Customize the appearance

Clean up

Server-rendered applications

​Install

​Script-tag installation

​Mount Checkout

​Handle events

​Payment results

​Customize the appearance

​Clean up

​Server-rendered applications

Install

Script-tag installation

Mount Checkout

Handle events

Payment results

Customize the appearance

Clean up

Server-rendered applications