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>
>;

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

clink.on('sdk-dialog-open', (paymentMethod: SdkButtonType) => {
  console.log('第三方支付弹窗打开', paymentMethod);
});

clink.on('sdk-dialog-close', (paymentMethod: SdkButtonType) => {
  console.log('第三方支付弹窗关闭', paymentMethod);
});

const clink = await loadClinkElements({
  sessionId,
  publishKey: PUBLIC_CLINK_PUBLISHABLE_KEY,
  environment: 'sandbox',
  presetOptions: {
    currencySelect: {
      // 只有 1 种货币时不显示选择器
      hideIfOneCurrency: true,
      switcher: {
        containerStyle: { gap: 8 },
        itemStyle: { borderColor: '#E7EBF3', background: '#FFFFFF' },
        selectedItemStyle: { borderColor: '#30343D', background: '#F5F5F5' },
        textStyle: { fontSize: 15, color: '#86909C' },
        selectedTextStyle: { color: '#30343D', fontWeight: 600 },
      },
    },
  },
});

┌─ containerStyle ──────────────────────────────────┐
│ ┌─ itemStyle ──────────┐ ┌─ itemStyle ──────────┐ │
│ │      ┌─ textStyle ─┐ │ │      ┌─ textStyle ─┐ │ │
│ │ [US] │ $99.00      │ │ │ [EU] │ €91.00      │ │ │
│ │      └─────────────┘ │ │      └─────────────┘ │ │
│ └──────────────────────┘ └──────────────────────┘ │
└───────────────────────────────────────────────────┘

switcher: {
  itemStyle: { border: '1px solid #E7EBF3' },
  // 选中时只改变边框颜色，粗细和圆角沿用 itemStyle
  selectedItemStyle: { borderColor: '#30343D' },
}

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

const expressOptions: PaymentMethodElementOptions = {
  mode: 'expressCheckout',
  options: {
    paymentMethodOrder: ['applePay', 'googlePay', 'paypal', 'link'],
    buttonHeight: 48,
    buttonRadius: 8,
    sdkButtons: {
      applePay: { buttonTheme: 'black', buttonType: 'buy' },
      googlePay: { buttonTheme: 'black', buttonType: 'pay' },
      paypal: { buttonType: 'pay' },
      // 不想展示 Link 时设为 never
      link: { visible: 'never' },
    },
  },
};

clink.on('session-success', () => {
  location.href = '/payment/result';
});

const paymentMethod = clink.createElement('paymentMethod', expressOptions);
paymentMethod.mount('#express-checkout');

type ExpressCheckoutPaymentMethod = 'applePay' | 'googlePay' | 'paypal' | 'link';
type ExpressCheckoutVisible = 'auto' | 'never';

interface ExpressCheckoutOptions {
  paymentMethodOrder?: ExpressCheckoutPaymentMethod[];
  buttonHeight?: number;
  buttonRadius?: number;
  hideError?: boolean;
  sdkButtons?: {
    applePay?: {
      visible?: ExpressCheckoutVisible;
      buttonTheme?: 'black' | 'white' | 'white-outline';
      buttonType?: 'buy' | 'check-out' | 'donate' | 'order' | 'plain';
    };
    googlePay?: {
      visible?: ExpressCheckoutVisible;
      buttonTheme?: 'black' | 'white';
      buttonType?:
        | 'book'
        | 'buy'
        | 'checkout'
        | 'donate'
        | 'order'
        | 'pay'
        | 'plain'
        | 'subscribe';
    };
    paypal?: {
      visible?: ExpressCheckoutVisible;
      buttonType?: 'buynow' | 'checkout' | 'donate' | 'pay' | 'subscribe';
    };
    link?: {
      visible?: ExpressCheckoutVisible;
    };
  };
}

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