JavaScript SDK

Clink JavaScript SDK 用于在浏览器应用中拉起 Clink Checkout，支持整页跳转和嵌入式 checkout 两种模式，并通过 publishable key 初始化。

安全提示： 浏览器端请使用 publishable key。不要在客户端暴露 Secret API keys。

NPM Package

在 npmjs.com 查看该包

Create Checkout Session

先在你的后端创建 checkout session，再拉起 checkout。

Checkout Session Guide

了解 hosted checkout 的完整工作流程。

安装

使用你偏好的包管理器从 npm 安装：

npm install @clink-ai/clink-js

yarn add @clink-ai/clink-js

pnpm add @clink-ai/clink-js

如果你需要浏览器全局版本，该包也提供了 UMD bundle。你可以自托管 dist/index.umd.js，加载后通过 window 上的 Clink.loadClink(...) 使用。

初始化

使用 publishable key 初始化 SDK：

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

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

SDK 在语法上接受 pk_test_*、pk_uat_* 和 pk_prod_*。但后台实际发给你的，沙盒是 pk_uat_*，生产是 pk_prod_*。如果你已经明确知道最终 checkout host，也可以直接传入 checkoutBaseUrl 跳过 bootstrap：

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

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

初始化参数

checkoutEnvironment：sandbox 或 production。未传 checkoutBaseUrl 时会使用它
checkoutBaseUrl：直接指定 checkout host。传入后会跳过 bootstrap
locale：会透传给 bootstrap 请求
origin：覆盖当前站点 origin
fetchImpl：为非浏览器运行环境提供自定义 fetch

未传 checkoutBaseUrl 时，SDK 会按以下顺序确定 bootstrap 环境：

checkoutEnvironment
CLINK_ENV

其中 CLINK_ENV=sandbox 会映射到 https://uat-api.clinkbill.com/api/sdk/bootstrap，CLINK_ENV=production 会映射到 https://api.clinkbill.com/api/sdk/bootstrap。

Redirect Checkout

如果你希望由 Clink 接管整页支付流程，可以使用 redirect 模式。

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({
      // 当后端返回 opaque session token 时，优先使用 sessionParam
      sessionParam: 'sess_xxx#token_xxx',
      replace: false,
    });
  });

redirectToCheckout 支持以下参数：

sessionParam：优先使用
sessionId：只有 session ID 时可用
replace：使用 window.location.replace(...) 而不是 assign(...)

如果同时传入 sessionParam 和 sessionId，会优先使用 sessionParam。

Embedded Checkout

如果你希望支付流程停留在当前页面中，可以使用嵌入式 checkout。

创建 Session 时用 uiMode: "hostedPage"。SDK 只要求你的后端返回一个可用的 checkoutUrl，它不会检查也不会改写 uiMode。uiMode: "elements" 属于另一个包 @clink-ai/clink-elements，那个挂载的是可组合的支付组件，不是完整的结账 iframe。同一个结账页选一种。

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 必须在你的后端创建 checkout session，并返回最终的 checkout URL。创建时用 uiMode: 'hostedPage'——SDK 会原样挂载返回的 URL，不改写其中的 query 参数，也不要求特定的 uiMode。

嵌入式参数

fetchSession：必填。必须返回 { sessionId, checkoutUrl, orderId? }
onEvent：接收 checkout 生命周期事件
autoResize：自动处理 iframe 高度变化。默认：true
autoDestroyOnComplete：支付成功后自动销毁实例。默认：true
pollStatus：可选的轮询函数，用于判断终态
pollIntervalMs：轮询间隔，单位毫秒。默认：2000

嵌入式实例 API

mount(container)：挂载到 CSS selector 或 HTMLElement
unmount()：移除 iframe，但保留实例可复用
destroy()：彻底销毁实例
on(type, handler)：订阅指定事件
getState()：返回 { mounted, destroyed }

事件与状态

嵌入式 checkout 会触发以下事件：

Event	Description
`ready`	checkout iframe 已就绪或已完成加载
`resize`	iframe 请求更新高度
`state_change`	checkout 状态发生变化
`complete`	到达终态
`hosted_return`	hosted checkout 将控制权返回父页面
`error`	SDK 或轮询过程出现错误

可用的嵌入式状态包括：

payment
pending
success
cancelled
error
expired

几个关键语义建议区分清楚：

complete：支付已经进入终态，可能来自 checkout 页面本身，也可能来自 pollStatus 的兜底确认
hosted_return：hosted success/cancel 页把控制权交还父页面，适合做 UI 收口或页面跳转
error：SDK 或轮询过程报错，不一定表示支付进入失败终态

Bootstrap 环境控制

SDK 支持通过 CLINK_ENV 固定远端 bootstrap 环境：

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

checkoutEnvironment 与 CLINK_ENV 保持一致，直接使用 sandbox / production。优先级如下：

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

错误处理

当参数校验、bootstrap 或嵌入式 checkout 初始化失败时，SDK 会抛出 ClinkError。

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

常见错误码包括：

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

概述

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

安装

初始化

初始化参数

Redirect Checkout

Embedded Checkout

嵌入式参数

嵌入式实例 API

事件与状态

Bootstrap 环境控制

错误处理

参考资料

NPM Package

Create Checkout Session

Checkout Session Guide

​安装

​初始化

​初始化参数

​Redirect Checkout

​Embedded Checkout

​嵌入式参数

​嵌入式实例 API

​事件与状态

​Bootstrap 环境控制

​错误处理

​参考资料

安装

初始化

初始化参数

Redirect Checkout

Embedded Checkout

嵌入式参数

嵌入式实例 API

事件与状态

Bootstrap 环境控制

错误处理

参考资料