Stripe checkout.session.completed事件后订单处理及元数据限制解决方案

核心问题 #

现有Stripe结账流程正常，但metadata的500字符限制无法容纳cartItems中的商品附加选项和客户备注，需解决如何通过WebSocket监听Stripe事件创建订单，以及其他可行替代方案。

现有Webhook代码 #

let endpointSecret;
endpointSecret =
  "whsec_bd73383ed0fcf9cfb27bd4929af341605ad32577dfd8825e1143425b846bb3c3";

router.post("/webhook", (request, response) => {
  const sig = request.headers["stripe-signature"];

  let data;
  let eventType;

  if (endpointSecret) {
    let event;

    try {
      event = stripe.webhooks.constructEvent(
        request.rawBody,
        sig,
        endpointSecret
      ); 
    } catch (err) {
      response.status(400).send(`Webhook Error: ${err.message}`);
      return;
    }

    data = event.data.object;
    eventType = event.type;
  } else {
    data = request.body.data.object;
    eventType = request.body.type;
  }

  // Handle the event
  if (eventType === "checkout.session.completed") {
    stripe.customers
      .retrieve(data.customer)
      .then((customer) => {
        console.log("customer:", customer);
        console.log("data:", data);
        createOrder(customer, data);
      })
      .catch((err) => console.log(err.message));
  }
});

WebSocket监听Stripe事件实现步骤 #

1. 后端搭建WebSocket服务 #

用ws库快速实现，先安装依赖：

npm install ws

在现有Express项目中集成WebSocket服务器：

const WebSocket = require('ws');
const wss = new WebSocket.Server({ port: 8080 }); // 可绑定到Express的HTTP服务器

// 存储客户端连接，按用户ID区分
const clients = new Map();

wss.on('connection', (ws) => {
  // 前端连接时传递用户标识
  ws.on('message', (message) => {
    const { userId } = JSON.parse(message);
    clients.set(userId, ws);
  });

  ws.on('close', () => {
    // 清理断开的连接
    clients.forEach((client, id) => {
      if (client === ws) clients.delete(id);
    });
  });
});

// 导出WebSocket服务器用于Webhook调用
module.exports = wss;

2. 修改Webhook推送订单数据 #

在checkout.session.completed事件处理中，从自有数据库取出完整购物车数据，推送给对应客户端：

const wss = require('./ws-server'); // 引入WebSocket服务器

// ... 现有Webhook代码 ...

if (eventType === "checkout.session.completed") {
  stripe.customers
    .retrieve(data.customer)
    .then(async (customer) => {
      // 从数据库取出完整购物车数据
      const cartItems = await getCartItemsFromDB(customer.id);
      const orderData = { customer, cartItems, session: data };
      
      // 找到对应用户的WebSocket连接并推送
      const client = clients.get(customer.id);
      if (client && client.readyState === WebSocket.OPEN) {
        client.send(JSON.stringify({ type: 'order_created', data: orderData }));
      }

      // 后端同步创建订单，保证可靠性
      createOrder(customer, orderData);
    })
    .catch((err) => console.log(err.message));
}

3. 前端连接WebSocket监听事件 #

用户进入结账页面时建立连接，监听订单完成事件：

// 前端代码（纯JS/React/Vue均可）
const ws = new WebSocket('ws://你的后端域名:8080');

ws.onopen = () => {
  // 发送用户ID给后端标识连接
  ws.send(JSON.stringify({ userId: '当前用户ID' }));
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  if (message.type === 'order_created') {
    // 收到通知后更新前端状态或跳转订单页
    console.log('订单已创建:', message.data);
    window.location.href = `/order/${message.data.orderId}`;
  }
};

ws.onclose = () => {
  console.log('WebSocket连接断开');
};

更简便的替代方案 #

1. 提前将购物车数据存入自有数据库（推荐） #

• 用户添加商品到购物车时，把包含附加选项、客户备注的完整cartItems存入数据库，生成唯一cartId。
• 创建Stripe Checkout Session时，仅将cartId存入metadata：

  const session = await stripe.checkout.sessions.create({
    // 其他配置...
    metadata: { cartId: '你的临时购物车ID' }
  });
  

• Webhook触发时，用cartId从数据库取出完整数据，执行createOrder逻辑，完全避开metadata字符限制。

2. 拆分数据到Line Items的description字段 #

• 每个商品的附加选项可写入对应Line Item的description字段（单字段最大5000字符）：

  const session = await stripe.checkout.sessions.create({
    line_items: [
      {
        price: 'price_xxx',
        quantity: 1,
        description: '商品名称 - 附加选项：XX，备注：XX'
      }
    ],
    metadata: { customerNote: '客户备注内容' }
  });
  

• Webhook中通过data.line_items取出每个商品的描述信息，拼接成完整订单数据。

3. 拆分Metadata字段 #

• 若一定要用metadata，可将长数据拆分为多个字段存储：

  metadata: {
    cartItem1Options: '商品1的附加选项',
    cartItem2Options: '商品2的附加选项',
    customerNote: '客户备注'
  }
  

• 适合数据量不大的场景，但维护性不如存自有数据库。

内容的提问来源于stack exchange，提问作者noobror