JavaScript SDK

Launch Clink Checkout from browser applications with redirect or embedded flows.

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

npm install @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',
});

Supported publishable key formats are pk_test_*, pk_uat_*, and pk_prod_*.

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:

1. checkoutEnvironment
2. 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.

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',
    });

    return await response.json();
    // {
    //   sessionId: 'sess_xxx',
    //   checkoutUrl: 'https://checkout.clinkbill.com/pay/sess_xxx%23token_xxx',
    //   orderId: 'ord_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. The SDK mounts that URL as-is and does not rewrite its query parameters.

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:

1. loadClink(..., { checkoutBaseUrl })
2. loadClink(..., { checkoutEnvironment })
3. 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

References

• Create Checkout Session
• Checkout Session Guide