Stripe支付按钮data-name属性是否自动纳入Webhook Payload？

首先直接给结论：Stripe支付按钮的data-name属性不会自动包含在Webhook发送的Payload中。

为什么data-name不在Webhook Payload里？ #

data-name本质上是Stripe支付按钮的展示性配置字段，主要作用是：

• 在支付界面上显示商品/服务名称
• 在Stripe后台仪表盘的交易记录里作为描述性信息展示
  它并不是用来传递自定义业务元数据的专用字段，因此不会被纳入Webhook的结构化事件Payload中。

正确传递自定义元数据到Webhook的方式 #

如果你需要在Webhook中获取交易相关的自定义元数据，应该使用Stripe官方提供的metadata参数，这是专门用于存储自定义键值对的字段，会完整出现在Webhook事件的Payload里。

示例：在Stripe.js配置支付按钮时添加元数据

当使用Stripe Elements支付按钮时，你可以在创建PaymentIntent的参数中指定metadata：

// 初始化Stripe
const stripe = Stripe('你的发布密钥');
const elements = stripe.elements();

// 创建支付按钮并配置元数据
const paymentButton = elements.create('paymentButton', {
  paymentIntentCreation: {
    parameters: {
      amount: 1000, // 金额，单位为分
      currency: 'usd',
      metadata: {
        order_id: 'ORD-2024-001',
        customer_id: 'CUST-12345',
        product_sku: 'PROD-SKU-007'
      }
    }
  },
  label: '支付'
});

// 挂载按钮到页面元素
paymentButton.mount('#payment-button-container');

在Webhook中获取元数据

当你收到payment_intent.succeeded这类事件时，元数据会包含在Payload的data.object.metadata中：

// 示例Webhook处理代码（Node.js）
app.post('/webhook', express.raw({type: 'application/json'}), (request, response) => {
  const event = request.body;

  switch (event.type) {
    case 'payment_intent.succeeded':
      const paymentIntent = event.data.object;
      console.log('支付成功，元数据：', paymentIntent.metadata);
      // 这里可以拿到order_id、customer_id等自定义数据
      break;
    // 处理其他事件类型...
    default:
      console.log(`未处理的事件类型 ${event.type}`);
  }

  response.json({received: true});
});

补充说明 #

如果你的集成方式是Stripe Checkout会话（而非直接用Elements按钮），同样需要在创建Checkout Session时指定metadata字段，该字段会同步到关联的PaymentIntent中，最终也能在Webhook里获取到。

总之，不要依赖data-name传递业务元数据，使用官方的metadata字段才是可靠的方案。

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