跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt

Use this file to discover all available pages before exploring further.

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
如果你需要浏览器全局版本，该包也提供了 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',
});
支持的 publishable key 格式包括 pk_test_*、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 环境：
  1. checkoutEnvironment
  2. 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。 
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: 'elements',
        returnUrl: `${window.location.origin}/complete.html?session_id={ELEMENTS_SESSION_ID}`,
      }),
    });

    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 必须在你的后端创建 checkout session，并返回最终的 checkout URL。对于嵌入式 checkout，创建 session 时需要传 uiMode: 'elements'。当 uiMode 为 elements 时，returnUrl 为必填，Clink 会在返回你的站点前将 {ELEMENTS_SESSION_ID} 替换为创建出的 session ID。SDK 会原样挂载返回的 URL，不会改写其中的 query 参数。

​
嵌入式参数

  • 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 会触发以下事件：
EventDescription
readycheckout iframe 已就绪或已完成加载
resizeiframe 请求更新高度
state_changecheckout 状态发生变化
complete到达终态
hosted_returnhosted checkout 将控制权返回父页面
errorSDK 或轮询过程出现错误
可用的嵌入式状态包括：
  • 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。 优先级如下：
  1. loadClink(..., { checkoutBaseUrl })
  2. loadClink(..., { checkoutEnvironment })
  3. 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

​
参考资料