收银台集成 - Element 集成

npm install @waffo/payment-sdk

import WaffoSDK from '@waffo/payment-sdk';

const sdk = new WaffoSDK('your-client-api-key', {
  env: 'prod',                // 'prod' | 'sandbox' | 'testing'
  locale: 'zh-Hans',
  preloadTokenization: false, // 只用 Payment Element 时关闭绑卡 iframe 预加载
});

const elements = sdk.createElements(sessionId, {
  appearance: {
    variables: { colorPrimary: '#1957ff', borderRadius: '8px' },
    layout: { type: 'vertical' },
  },
});

<form id="wechat-form"></form>

const wechat = await elements.create('WECHATPAY', { customRender: true });

const form = document.getElementById('wechat-form');
const fields = document.createElement('div');
const pay = document.createElement('button');
pay.type = 'submit';
form.replaceChildren(fields, pay);

let inputs = [];
let schemaKey = '';

function render(state) {
  const method = state?.payMethod;
  // 仅在字段定义变化时重建输入框，避免清空用户已输入的内容
  const key = JSON.stringify(method?.requiredFields ?? []);
  if (key !== schemaKey) {
    schemaKey = key;
    fields.replaceChildren();
    // options 非空时渲染下拉框：显示 name，提交 code
    inputs = (method?.requiredFields ?? []).map((field) => {
      const control = document.createElement(field.options?.length ? 'select' : 'input');
      control.name = field.field;
      control.required = field.required;
      for (const option of field.options ?? []) control.add(new Option(option.name, option.code));
      fields.append(control);
      return control;
    });
  }
  pay.hidden = !state?.ready || !method;
  pay.disabled = !['ready', 'error'].includes(state?.phase);
  pay.textContent = '微信支付';
}

wechat.on('change', render);
render(wechat.getState()); // 读取一次当前状态，避免错过初始化期间的 change

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  const userFields = Object.fromEntries(inputs.map((c) => [c.name, c.value]));
  try {
    await elements.confirmPayment(wechat, {
      payMethodName: wechat.payMethod.payMethodName,
      userFields,
    });
  } catch (err) {
    message.textContent = err.message;
  }
});

payButton.addEventListener('click', async () => {
  try {
    await elements.confirmPayment(); // 结果同样会触发 payment 事件
  } catch (err) {
    message.textContent = err.message; // err.code 一定存在，处理方式见「错误处理」
  }
});

elements.confirmPayment(element?: PaymentElement, options?: ConfirmPaymentOptions): Promise<PaymentResult>

elements.on('payment', (result) => {
  const data = result.data;

  if (data && 'sessionType' in data) {
    // 订阅 session：读取 data.subscription
  } else {
    console.log('Waffo 订单号', data?.acquiringOrderId);
  }

  if (result.status === 'succeeded') {
    location.href = '/success';
  } else if (result.status === 'processing') {
    message.textContent = '支付处理中，请等待最终结果';
  } else if (result.status === 'failed') {
    message.textContent = result.message ?? '支付失败';
  }
});

elements.on('error', (err) => {
  message.textContent = err.message;
});

on(event: string, handler: (payload) => void): () => void
off(event: string, handler: (payload) => void): void

const handleChange = (state) => { /* ... */ };

// 方式一：用 on 的返回值取消
const unsubscribe = element.on('change', handleChange);
unsubscribe();

// 方式二：用 off 取消，需传入同一个函数引用
element.on('change', handleChange);
element.off('change', handleChange);

element.on('ready', (state) => {
  console.log('可用支付方式', state.availablePayMethods);
});

element.on('change', (state) => {
  payButton.hidden = !state.ready || state.confirmTrigger !== 'merchant';
  payButton.disabled = !['ready', 'error'].includes(state.phase);
  payButton.textContent = state.loading ? '处理中…' : '支付';
});

{
  "phase": "ready",
  "loading": false,
  "ready": true,
  "complete": false,
  "payMethodName": "CARD",
  "availablePayMethods": ["APPLEPAY", "GOOGLEPAY", "CARD"],
  "confirmTrigger": "merchant"
}

card.on('error', (err) => {
  cardMessage.textContent = err.message;
});

elements.on('payment', (result) => {
  const data = result.data;
  const isSubscription = data && 'sessionType' in data;

  switch (result.status) {
    case 'succeeded':
      location.href = isSubscription
        ? `/success?subscription=${data.subscription?.subscriptionId}`
        : `/success?order=${data?.acquiringOrderId}`;
      break;
    case 'processing':
      message.textContent = '支付处理中，请等待最终结果';
      break;
    case 'failed':
      message.textContent = result.message ?? '支付失败';
      break;
    case 'requires_action':
      // 仅 handleNextAction: false 时出现，见「3DS 与后续动作」
      break;
  }
});

{
  "status": "succeeded",
  "data": {
    "paymentRequestId": "req_20261025000001",
    "merchantOrderId": "ORDER_20261025001",
    "acquiringOrderId": "A2026102500000001",
    "orderStatus": "PAY_SUCCESS",
    "orderAction": null
  }
}

elements.on('redirect', ({ url }) => {
  // 保存恢复页面所需的信息；不要在这里跳转页面，否则会打断 SDK 发起的跳转
  sessionStorage.setItem('pendingSessionId', elements.sessionId);
});

elements.on('error', (err) => {
  message.textContent = err.message;

  if (['A0063', 'A0064'].includes(err.code)) {
    // session 已不可用：请服务端新建 session，再调用 updateSessionId(newId)
  }
});

elements.on('redirect', ({ url }) => {
  sessionStorage.setItem('pendingSessionId', elements.sessionId);
});

const elements = sdk.createElements(sessionId, { handleNextAction: false });

elements.on('payment', (result) => {
  if (result.status !== 'requires_action') return;

  const data = result.data;
  const raw = data && 'sessionType' in data
    ? data.subscription?.subscriptionAction
    : data?.orderAction;
  if (!raw) return;

  try {
    const action = JSON.parse(raw);
    // 根据 action 中的实际字段展示指引或跳转；跳转前校验 URL 协议和目标
  } catch {
    message.textContent = '无法解析支付动作';
  }
});

await elements.updateAppearance({
  variables: { colorPrimary: '#5b8ef3', colorBackground: '#1a1a1a', colorText: '#ffffff' },
  layout: { type: 'horizontal', maxColumns: 3 },
});

await elements.updateAppearance({
  variables: {
    colorPrimary: '#1957ff',
    spacing: { button: '8px', accordionItem: '8px', gridRow: '16px' },
  },
  rules: {
    '.Input': { border: '1px solid #d0d5dd', borderRadius: '10px' },
    '.Input:focus': 'border-color: var(--colorPrimary)',
    '.PayMethodLogo': { width: '32px', height: '32px' },
  },
});

const elements = sdk.createElements(sessionId, {
  appearance: { inputs: 'condensed', variables: { colorPrimary: '#1957ff' } },
});

rules: {
  '.Input': { padding: '11px 12px', fontWeight: '400', fontSize: '16px' },
}

// session 已在服务端更新：传入相同的 sessionId
await elements.updateSessionId(sessionId);

// 支付失败后服务端新建了 session：传入新的 sessionId
await elements.updateSessionId(newSessionId);

element.unmount();   // 移除单个组件
elements.destroy();  // 移除所有组件，并关闭仍在显示的 3DS / 付款指引弹层
sdk.destroy();       // 释放 SDK 资源

payButton.addEventListener('click', async () => {
  try {
    await elements.confirmPayment();
  } catch (err) {
    if (err.code === 'SDK_ELEMENTS_BUSY') return; // 已在处理，忽略重复点击
    showError(err.message); // 替换显示，而不是追加
  }
});

elements.on('error', (err) => showError(err.message));