Stripe Webhook未返回全部元数据问题求助

架构老林

2026-6-30

问题

使用PHP创建Stripe Checkout Session时，我向metadata参数传入了10组键值对，代码如下：

$checkout_session = \Stripe\Checkout\Session::create([
    'payment_method_types' => ['card'],
    'client_reference_id' => $accountnumber,
    'mode' => 'payment',
    'line_items' => [[
      'price_data' => [
        'currency' => $currencycode,
        'product_data' => [
          'name' => 'Invoice Total',
        ],
        'unit_amount' => $invoicetotal,
      ],
      'quantity' => 1,
    ]],
    'payment_intent_data' => [
      'application_fee_amount' => $timesavrfee,
      'receipt_email' => $payeremail
    ],
    'success_url' => $successurl.'?session_id={CHECKOUT_SESSION_ID}&cid='.$companyid,
    'cancel_url' => $cancelurl.'?session_id={CHECKOUT_SESSION_ID}&cid='.$companyid,
    'metadata' => ['familyid'=>$familyid,
                   'transactionreference'=>$transactionreference,
                   'companyid'=>$companyid,
                   'paymenttype'=>$paymenttype,
                   'payer'=>$primarypayer,
                   'invoicedate'=>$invoicedate,
                   'feecomment'=>$feecomment,
                   'feeamount'=>$feeamount,
                   'processingfeeschargeitem'=>$processingfeeschargeitem,
                   'passonprocessingfees'=>$passonprocessingfees]
  ],['stripe_account' => $accountid]);

我已通过日志确认所有参数均有值，但Stripe返回的checkout.session.completed事件Webhook仅包含其中6个元数据，另外4个完全不存在（并非为空）。查看Stripe仪表盘的Webhook历史，返回的metadata如下：

"metadata": {
    "payer": "M",
    "companyid": "2142",
    "invoicedate": "2024-01-26 00:00:00",
    "paymenttype": "ONL",
    "transactionreference": "1157",
    "familyid": "29764010"
  },

缺失的4个元数据为：

feecomment
feeamount
processingfeeschargeitem
passonprocessingfees

根据Stripe文档，元数据最多支持50个键（键名最长40字符，值最长500字符），我确认未违反该限制。请问为何仅能收到6个元数据，另外4个无法返回？

可能的原因与解决方案

Connect场景下的元数据层级问题
从代码里的stripe_account参数能看出你在使用Connect模式，根节点的metadata属于平台账户，而checkout.session.completed事件默认返回的是关联交易（Payment Intent）的元数据。你可以尝试把缺失的4个字段移到payment_intent_data下的metadata中，确保数据关联到实际交易：
```
'payment_intent_data' => [
  'application_fee_amount' => $timesavrfee,
  'receipt_email' => $payeremail,
  'metadata' => [
    'feecomment'=>$feecomment,
    'feeamount'=>$feeamount,
    'processingfeeschargeitem'=>$processingfeeschargeitem,
    'passonprocessingfees'=>$passonprocessingfees
  ]
],
```
Webhook事件的精简数据限制
Stripe Webhook默认返回的是精简版对象，部分字段会被过滤。你可以登录Stripe仪表盘，找到对应的Webhook端点，把该事件的「数据包含」选项从「精简」改为「完整」，这样就能获取到全部元数据字段。
隐性格式问题导致字段丢弃
虽然你确认键名长度合规，但如果缺失字段的键名或值包含换行、制表符等非打印字符，可能会被Stripe自动丢弃。检查这些字段的实际值，替换为纯文本后再测试。
SDK版本兼容性bug
若你使用的Stripe PHP SDK版本较旧，可能存在metadata字段处理的漏洞。尝试更新SDK到最新稳定版，再重新发起创建Session的请求测试。

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