Stripe checkout session设置的metadata未在返回及webhook事件中返回问题

问题原因 #

• Stripe Python SDK版本过旧，to_dict() 方法未实现递归序列化，嵌套的StripeObject类型的metadata在转换为字典时显示为空，但实际数据已经正常接收。
• Webhook端点配置的API版本与后端Stripe SDK使用的API版本不匹配，导致返回的字段结构存在差异，metadata未被正常解析。
• Checkout Session的metadata默认不会自动同步到关联的Payment Intent、Customer等关联对象，因此在payment_intent.created这类非Checkout Session自身的事件中无法直接拿到该字段。

解决方案 #

1. 验证数据实际存在：直接访问metadata的具体字段确认数据是否正常接收，无需依赖序列化后的字典打印结果，示例代码如下：

# 在webhook处理逻辑中添加测试代码
checkout_session = event['data']['object']
print(checkout_session['metadata']['key']) # 正常可以输出你传入的'val'

2. 升级Stripe Python SDK到最新版本，解决序列化显示问题：

pip install --upgrade stripe

3. 对齐API版本：在Stripe Dashboard的Webhook设置页面核对当前端点的API版本，在代码中指定相同版本保证字段结构一致：

stripe.api_key = STRIPE_SECRET_KEY
stripe.api_version = '2024-06-20' # 替换为webhook配置的对应版本号

4. 如需在关联对象的事件中获取metadata，创建Checkout Session时单独添加对应传参：

checkout_session = stripe.checkout.Session.create(
    metadata={"key": "val"},
    # 向关联的Payment Intent传递metadata
    payment_intent_data={"metadata": {"key": "val"}},
    # 向关联的Customer传递metadata（可选）
    customer_metadata={"key": "val"},
    payment_method_types=['card'],
    line_items=request.form.get("lineItems", LINE_ITEMS),
    success_url=f'{request.environ["HTTP_ORIGIN"]}/success',
    cancel_url=f'{request.environ["HTTP_ORIGIN"]}/cancel',
    mode='payment'
)

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