JavaScript SDK

The Clink JavaScript SDK helps you launch Clink Checkout in browser-based applications. It supports both full-page redirects and embedded checkout, and initializes with a publishable key.

Security Note: Use a publishable key in browser code. Never expose your Secret API keys on the client side.

NPM Package

View the package on npmjs.com

Create Checkout Session

Create a checkout session on your backend before launching checkout.

Checkout Session Guide

Learn how hosted checkout sessions work end to end.

Installation

Install the SDK from npm with your preferred package manager:

npm install @clink-ai/clink-js

yarn add @clink-ai/clink-js

pnpm add @clink-ai/clink-js

If you need a browser global build, the package also ships a UMD bundle. After self-hosting dist/index.umd.js, the SDK is exposed as Clink.loadClink(...) on window.

Initialization

Initialize the SDK with your publishable key:

import { loadClink } from '@clink-ai/clink-js';

const clink = await loadClink('pk_uat_xxxxxxxxx', {
  checkoutEnvironment: 'sandbox',
  locale: 'en-US',
});

The SDK syntactically accepts pk_test_*, pk_uat_*, and pk_prod_*. The keys you actually get from the dashboard are pk_uat_* in sandbox and pk_prod_* in production. If you already know the final checkout host, you can skip bootstrap by passing checkoutBaseUrl directly:

import { loadClink } from '@clink-ai/clink-js';

const clink = await loadClink('pk_prod_xxxxxxxxx', {
  checkoutBaseUrl: 'https://checkout.clinkbill.com',
});

Init Options

checkoutEnvironment: sandbox or production. Used when checkoutBaseUrl is not provided.
checkoutBaseUrl: Checkout host used directly by the SDK. When set, bootstrap is skipped.
locale: Forwarded during bootstrap.
origin: Override the current site origin.
fetchImpl: Custom fetch implementation for non-browser runtimes.

When checkoutBaseUrl is omitted, the SDK resolves bootstrap in this order:

checkoutEnvironment
CLINK_ENV

CLINK_ENV=sandbox maps to https://uat-api.clinkbill.com/api/sdk/bootstrap, and CLINK_ENV=production maps to https://api.clinkbill.com/api/sdk/bootstrap.

Redirect Checkout

Use redirect checkout when you want Clink to take over the full page flow.

import { loadClink } from '@clink-ai/clink-js';

const clink = await loadClink('pk_uat_xxxxxxxxx', {
  checkoutEnvironment: 'sandbox',
});

document
  .getElementById('checkout-button')
  ?.addEventListener('click', async () => {
    await clink.redirectToCheckout({
      // Preferred when your backend returns an opaque session token
      sessionParam: 'sess_xxx#token_xxx',
      replace: false,
    });
  });

redirectToCheckout accepts:

sessionParam: Preferred when available.
sessionId: Used when you only have the session ID.
replace: Uses window.location.replace(...) instead of assign(...).

When both sessionParam and sessionId are provided, sessionParam wins.

Embedded Checkout

Use embedded checkout when you want the payment flow to stay inside your page.

Create the Session with uiMode: "hostedPage". The SDK only needs your backend to return a usable checkoutUrl — it does not inspect or rewrite uiMode.uiMode: "elements" belongs to the separate @clink-ai/clink-elements package, which mounts composable payment components rather than a full checkout iframe. Pick one per checkout page.

import { loadClink } from '@clink-ai/clink-js';

const clink = await loadClink('pk_uat_xxxxxxxxx', {
  checkoutEnvironment: 'sandbox',
});

const embedded = await clink.initEmbeddedCheckout({
  async fetchSession() {
    const response = await fetch('/api/clink/checkout-session', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        uiMode: 'hostedPage',
        successUrl: `${window.location.origin}/complete.html`,
        cancelUrl: `${window.location.origin}/cart`,
      }),
    });

    return await response.json();
    // {
    //   sessionId: 'sess_xxx',
    //   checkoutUrl: 'https://checkout.clinkbill.com/pay/sess_xxx%23token_xxx',
    //   orderId: 'order_xxx'
    // }
  },
  onEvent(event) {
    console.log(event.type, event.payload);
  },
  async pollStatus({ sessionId, orderId, attempt }) {
    const response = await fetch(
      `/api/clink/checkout-status?sessionId=${sessionId}`,
    );
    const result = await response.json();

    if (result.state === 'pending' || result.state === 'payment') {
      return null;
    }

    return {
      state: result.state,
      payload: {
        orderId,
        attempt,
      },
    };
  },
});

embedded.mount('#clink-checkout');

fetchSession must create a checkout session on your backend and return the final checkout URL. Create it with uiMode: 'hostedPage' — the SDK mounts the returned URL as-is and does not rewrite its query parameters, nor does it require any particular uiMode.

Embedded Options

fetchSession: Required. Must resolve { sessionId, checkoutUrl, orderId? }.
onEvent: Receives all checkout lifecycle events.
autoResize: Automatically applies iframe height updates. Default: true.
autoDestroyOnComplete: Automatically destroys the embedded instance after a successful payment. Default: true.
pollStatus: Optional polling hook for terminal state detection.
pollIntervalMs: Poll interval in milliseconds. Default: 2000.

Embedded Instance API

mount(container): Mount into a CSS selector or HTMLElement.
unmount(): Remove the iframe but keep the instance reusable.
destroy(): Fully dispose the instance.
on(type, handler): Subscribe to a specific event type.
getState(): Returns { mounted, destroyed }.

Events and States

Embedded checkout can emit the following events:

Event	Description
`ready`	The checkout iframe is ready or has finished loading.
`resize`	The iframe requests a height update.
`state_change`	Checkout state changed.
`complete`	A terminal state was reached.
`hosted_return`	The hosted checkout returned control to the parent page.
`error`	SDK or polling error.

Possible embedded states are:

payment
pending
success
cancelled
error
expired

Semantics to keep in mind:

complete: The checkout reached a terminal payment state, either from the checkout page itself or via pollStatus.
hosted_return: A hosted success or cancel page returned control to the parent page. Use this for UI cleanup or navigation.
error: An SDK or polling failure, not necessarily a payment terminal state.

Bootstrap Environment

The SDK supports fixing the remote bootstrap environment with CLINK_ENV:

CLINK_ENV=sandbox → https://uat-api.clinkbill.com/api/sdk/bootstrap
CLINK_ENV=production → https://api.clinkbill.com/api/sdk/bootstrap

checkoutEnvironment uses the same values: sandbox and production. Priority order:

loadClink(..., { checkoutBaseUrl })
loadClink(..., { checkoutEnvironment })
CLINK_ENV

Error Handling

The SDK throws ClinkError for validation, bootstrap, and embedded checkout failures.

import {
  CLINK_ERROR_CODES,
  ClinkError,
  loadClink,
} from '@clink-ai/clink-js';

try {
  const clink = await loadClink('pk_uat_xxxxxxxxx', {
    checkoutEnvironment: 'sandbox',
  });

  await clink.redirectToCheckout({
    sessionId: 'sess_xxx',
  });
} catch (error) {
  if (error instanceof ClinkError) {
    if (error.code === CLINK_ERROR_CODES.INVALID_PUBLIC_KEY) {
      console.error('Invalid publishable key');
    }
  }
}

Common error codes include:

INVALID_PUBLIC_KEY
INVALID_CHECKOUT_ENV
BOOTSTRAP_REQUEST_FAILED
INVALID_BOOTSTRAP_RESPONSE
INVALID_REDIRECT_PARAMS
INVALID_EMBEDDED_OPTIONS
INVALID_SESSION_ID
SESSION_ID_FETCH_FAILED
EMBEDDED_CHECKOUT_DISABLED
CONTAINER_NOT_FOUND
NOT_IN_BROWSER

API Documentation

Checkout Session

Payment

Payment Instrument

Order

Agent Payment Session

Refund

Product

Price

Coupon

Promotion Code

Subscription

Test Clock

Customer Portal

Webhook Endpoint Management

Webhooks

NPM Package

Create Checkout Session

Checkout Session Guide

Installation

Initialization

Init Options

Redirect Checkout

Embedded Checkout

Embedded Options

Embedded Instance API

Events and States

Bootstrap Environment

Error Handling

References

NPM Package

Create Checkout Session

Checkout Session Guide

​Installation

​Initialization

​Init Options

​Redirect Checkout

​Embedded Checkout

​Embedded Options

​Embedded Instance API

​Events and States

​Bootstrap Environment

​Error Handling

​References

Installation

Initialization

Init Options

Redirect Checkout

Embedded Checkout

Embedded Options

Embedded Instance API

Events and States

Bootstrap Environment

Error Handling

References