Hosted Checkout 接入

merchant_order_id      -- 你的订单号
customer_id            -- 你系统里的用户
product_snapshot       -- 商品名、单价、数量（下单那一刻的快照）
original_amount        -- 金额
original_currency      -- 币种
clink_session_id       -- Clink 返回的 sessionId
clink_order_id         -- 付款产生的 orderId
payment_status         -- 你自己的支付状态
fulfillment_status     -- 发货状态，和支付状态分开存
created_at
updated_at

// 回跳页面
const orderId = new URLSearchParams(location.search).get('orderId');
const order = await fetch(`/api/orders/${orderId}`).then((r) => r.json());

if (order.paymentStatus === 'paid') {
  showSuccess();
} else if (order.paymentStatus === 'pending') {
  showPending();   // 「支付确认中」，几秒后再查一次
} else {
  showFailed();
}

import { ClinkWebhook, ClinkWebhookSignatureError } from '@clink-ai/clink-typescript-sdk';

const webhook = new ClinkWebhook({
  signatureKey: process.env.CLINK_WEBHOOK_SIGNING_KEY,
});

// 验签失败会抛 ClinkWebhookSignatureError，成功则返回解析好的事件
const event = webhook.verifyAndGet({
  timestamp: req.headers['x-clink-timestamp'],
  body: rawBody,
  headerSignature: req.headers['x-clink-signature'],
});

// 注意：express.raw()，不是 express.json()
app.post(
  '/api/webhooks/clink',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const rawBody = req.body.toString('utf8');

    if (!verifySignature(rawBody, req.headers)) {
      return res.status(401).send('invalid signature');
    }

    const event = JSON.parse(rawBody);

    // 1. 幂等：同一个事件 ID 只处理一次
    const seen = await db.webhookEvents.findById(event.id);
    if (seen) return res.status(200).send('ok');

    try {
      await handleEvent(event);
      await db.webhookEvents.create({ id: event.id, type: event.type });
    } catch (err) {
      // 处理失败就别返回 2xx，让 Clink 重试
      logger.error({ err, eventId: event.id }, 'webhook failed');
      return res.status(500).send('retry later');
    }

    // 2. 状态写入成功之后才返回 200
    res.status(200).send('ok');
  }
);

async function handleEvent(event) {
  const obj = event.data.object;

  // 退款事件里没有你的订单号，用 orderId 反查
  if (event.type.startsWith('refund.')) {
    const local = await db.orders.findByClinkOrderId(obj.orderId);
    if (!local) return;

    if (event.type === 'refund.succeeded') {
      await db.orders.update(local.id, { paymentStatus: 'refunded' });
      await revokeOnce(local.id);
    }
    return;
  }

  if (!event.type.startsWith('order.')) return;

  // 下面这三步对所有 order.* 事件都一样，所以放在 switch 外面

  // 1. 双重匹配：订单号和 Session 都要对得上
  const local = await db.orders.findById(obj.merchantReferenceId);
  if (!local || local.clinkSessionId !== obj.sessionId) {
    logger.warn({ orderId: obj.orderId }, 'order mismatch, skipped');
    return;
  }

  // 2. 已经是终态就不动了。迟到的失败事件不能把成功改回去
  if (['paid', 'refunded'].includes(local.paymentStatus)) return;

  switch (event.type) {
    case 'order.succeeded':
      await db.orders.update(local.id, {
        paymentStatus: 'paid',
        clinkOrderId: obj.orderId,
      });
      await fulfillOnce(local.id);       // 3. 发货本身也要幂等
      break;

    case 'order.failed':
      await db.orders.update(local.id, {
        paymentStatus: 'payment_failed',
        failureCode: obj.failureCode,
        failureMessage: obj.failureMessage,
      });
      break;

    case 'order.next_action':
      await db.orders.update(local.id, { paymentStatus: 'action_required' });
      break;
  }
}

cloudflared tunnel --url http://127.0.0.1:3000 --no-autoupdate

// send-test-event.mjs
import crypto from 'node:crypto';

const event = {
  id: 'evt_test_001',                       // 换个 id 测新事件，用同一个 id 测去重
  type: 'order.succeeded',
  object: 'event',
  created: Date.now(),
  data: {
    object: {
      orderId: 'ord_test_001',
      merchantReferenceId: 'order_10001',   // 换成你库里真实存在的订单号
      sessionId: 'sess_test_001',           // 要和该订单的 clinkSessionId 一致
      status: 'success',
    },
  },
};

const body = JSON.stringify(event);
const timestamp = String(Date.now());
const signature = crypto
  .createHmac('sha256', process.env.CLINK_WEBHOOK_SIGNING_KEY)
  .update(`${timestamp}.${body}`)
  .digest('hex');

const res = await fetch('http://127.0.0.1:3000/api/webhooks/clink', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Clink-Timestamp': timestamp,
    'X-Clink-Signature': signature,
    'X-Clink-SignType': 'SHA256',
  },
  body,
});

console.log(res.status, await res.text());