Elements 嵌入式收银台

// 这是商户自己的后端接口，不是 Clink 的浏览器 API
app.post('/api/payments/elements-session', requireUser, async (req, res) => {
  const { productId, quantity } = req.body;

  // 金额在服务端重算，不信浏览器传来的价格
  const quote = await catalog.quote(productId, quantity);

  const order = await orders.createPending({
    customerId: req.user.id,
    amount: quote.amount,
    currency: quote.currency,
  });

  const session = await clinkRequest('/checkout/session', {
    customerEmail: req.user.email,
    merchantReferenceId: order.id,
    originalAmount: quote.amount,
    originalCurrency: quote.currency,
    priceDataList: quote.items,
    uiMode: 'elements',
    returnUrl: `${APP_ORIGIN}/payment/return?session_id={ELEMENTS_SESSION_ID}`,
  });

  await orders.bindSession(order.id, session.sessionId);

  // 这是自定义的前端响应，字段越少越好
  res.json({ sessionId: session.sessionId });
});

{
  "sessionId": "sess_xxxxxxxx",
  "uiMode": "elements",
  "returnUrl": "https://merchant.example.com/payment/return?session_id=sess_xxxxxxxx",
  "url": "https://uat-checkout.clinkbill.com/...",
  "merchantReferenceId": "merchant_order_xxx",
  "expireTime": "2026-07-30 12:00:00"
}

import { loadClinkElements } from '@clink-ai/clink-elements';

// 调的是商户自己的后端，不是 Clink
const response = await fetch('/api/payments/elements-session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ productId, quantity }),
});

if (!response.ok) throw new Error('Unable to create checkout session');
const { sessionId } = await response.json();

const clink = await loadClinkElements({
  sessionId,
  publishKey: PUBLIC_CLINK_PUBLISHABLE_KEY,
  environment: 'sandbox',
  presetOptions: {
    locale: 'zh-CN',
    theme: 'light',
    primaryColor: '#1677FF',
  },
});

const paymentMethod = clink.createElement('paymentMethod');
paymentMethod.mount('#payment-method');

// 需要客户选币种时才创建，且必须晚于 paymentMethod
const currencySelect = clink.createElement('currencySelect');
currencySelect.mount('#currency-select');

let canSubmit = false;
let submitting = false;

clink.on('submit-enabled', (enabled) => {
  canSubmit = enabled;
  payButton.disabled = !enabled || submitting;
});

// 第三方按钮接管提交时隐藏自己的按钮
clink.on('submit-visible', (visible) => {
  payButton.hidden = !visible;
});

payButton.addEventListener('click', () => {
  if (!canSubmit || submitting) return;
  submitting = true;
  payButton.disabled = true;
  clink.submit();
});

import type { SdkButtonOptions } from '@clink-ai/clink-elements';

const sdkButtons: SdkButtonOptions = {
  applePay: {
    buttonHeight: 48,
    buttonRadius: 8,
    buttonTheme: 'black',
    buttonType: 'buy',
  },
  googlePay: {
    buttonHeight: 48,
    buttonRadius: 8,
    buttonTheme: 'black',
    buttonType: 'pay',
  },
  link: {
    buttonHeight: 48,
    buttonRadius: 8,
  },
  paypal: {
    buttonHeight: 48,
    buttonRadius: 8,
    buttonType: 'pay',
  },
};

const clink = await loadClinkElements({
  publishKey: PUBLIC_CLINK_PUBLISHABLE_KEY,
  environment: 'sandbox',
  sessionId,
  presetOptions: {
    locale: 'zh-CN',
    theme: 'light',
    sdkButtons,
  },
});

interface SdkButtonOptions {
  applePay?: {
    buttonHeight?: number;
    buttonRadius?: number;
    buttonTheme?: 'black' | 'white' | 'white-outline';
    buttonType?: 'buy' | 'check-out' | 'donate' | 'order' | 'plain';
  };
  googlePay?: {
    buttonHeight?: number;
    buttonRadius?: number;
    buttonTheme?: 'black' | 'white';
    buttonType?:
      | 'book'
      | 'buy'
      | 'checkout'
      | 'donate'
      | 'order'
      | 'pay'
      | 'plain'
      | 'subscribe';
  };
  link?: {
    buttonHeight?: number;
    buttonRadius?: number;
  };
  paypal?: {
    buttonHeight?: number;
    buttonRadius?: number;
    buttonType?: 'buynow' | 'checkout' | 'donate' | 'pay' | 'subscribe';
  };
}

import type { SdkButtonInitializedData } from '@clink-ai/clink-elements';

const handleSdkButtonInitialized = (
  status: SdkButtonInitializedData,
) => {
  // { applePay: true, googlePay: false, link: true }
  console.log('第三方按钮状态', status);
};

clink.on('sdk-button-initialized', handleSdkButtonInitialized);

const paymentMethod = clink.createElement('paymentMethod');
paymentMethod.mount('#payment-method');

type SdkButtonInitializedData = Partial<
  Record<'applePay' | 'googlePay' | 'link' | 'paypal', boolean>
>;

clink.on('amount-change', ({ amount }) => {
  promoSection.hidden = !amount.enablePromotionCode;
  renderApplied(amount.promotionCodeInfo);
  updateTotal(amount.dueTodayAmount, amount.currency);
});

applyButton.addEventListener('click', () => {
  setPromoLoading(true);
  clink.promoCodeChange({ type: 'apply', code: promoInput.value });
});

removeButton.addEventListener('click', () => {
  setPromoLoading(true);
  clink.promoCodeChange({ type: 'clear' });
});

clink.on('promo-code-error', ({ message }) => {
  setPromoLoading(false);
  showPromoError(message);
});

import { loadClinkElements, ClinkApiError } from '@clink-ai/clink-elements';

try {
  const clink = await loadClinkElements(options);
} catch (error: unknown) {
  if (error instanceof ClinkApiError) {
    // Clink 接口返回的业务错误，message 来自接口
    showInitError(error.message);
  } else if (error instanceof TypeError) {
    // 网络或请求层失败，可以提示重试
    showNetworkError();
  } else {
    // 参数错误、响应解析失败等其余情况
    showUnknownError(error);
  }
}

try {
  const paymentMethod = clink.createElement('paymentMethod');
  paymentMethod.mount('#payment-method');
} catch (err) {
  // 组件创建顺序、重复创建、挂载目标不存在都会走到这里
  reportIntegrationBug(err);
}