如何使用Stripe插入metadata详情或扩展新的自定义属性

你当前将metadata参数放在line_items的子数组中是无效的，Stripe 公开的Checkout Session创建参数中，line_items单个条目没有直接的metadata入参，所以你写的这部分内容不会被Stripe接收，自然无法在webhook中返回。

你可以根据需求选择以下实现方案：

• 方案1：添加Session级全局Metadata
  直接将metadata参数放在Session::create的一级参数中，所有自定义内容会挂载到整个结账会话对象上，在checkout.session.completed等webhook事件中可直接读取。

$session = \Stripe\Checkout\Session::create([
    'success_url' => 'https://example.com/success',
    'cancel_url' => 'https://example.com/cancel',
    'payment_method_types' => ['card'],
    'line_items' => [
        [
            'price' => $price_id,
            'quantity' => 1,
        ],
    ],
    'mode' => 'payment',
    // 全局Metadata 所有自定义字段可放在这里
    'metadata' => [
        'prod_id' => 'TEST',
        'custom_field1' => '自定义值1',
        'custom_field2' => '自定义值2'
    ]
]);

• 方案2：将Metadata关联到付款意图（Payment Intent）
  如果需要自定义内容在付款相关的webhook（比如payment_intent.succeeded）、付款记录详情中也能查到，可以把Metadata放在payment_intent_data参数下：

$session = \Stripe\Checkout\Session::create([
    'success_url' => 'https://example.com/success',
    'cancel_url' => 'https://example.com/cancel',
    'payment_method_types' => ['card'],
    'line_items' => [
        [
            'price' => $price_id,
            'quantity' => 1,
        ],
    ],
    'mode' => 'payment',
    // 关联到付款意图的Metadata
    'payment_intent_data' => [
        'metadata' => [
            'prod_id' => 'TEST',
            'pay_custom_field' => '付款相关自定义值'
        ]
    ]
]);

• 多商品单独标记方案
  如果你的结账会话包含多个商品，需要分别给每个商品加自定义标识，可以把所有商品的元数据拼装为JSON字符串后，存入Session级Metadata的单个键中，触发webhook后再解析即可：

// 多商品元数据示例
$lineItemsMeta = json_encode([
    ['prod_id' => 'TEST1', 'prod_name' => '商品1'],
    ['prod_id' => 'TEST2', 'prod_name' => '商品2']
]);

$session = \Stripe\Checkout\Session::create([
    // 其他参数不变
    'metadata' => [
        'all_line_items_meta' => $lineItemsMeta
    ]
]);

注意：Stripe Metadata 限制：单条Metadata的键和值最大长度均为500字符，单个对象最多支持50个Metadata键，超出限制会报错

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