处理Stripe `charge.refunded` WebHook调用：如何关联自有订单

方案1：将client_reference_id复制到Checkout Session的metadata #

创建Checkout Session时，除了设置client_reference_id，同时把该值写入metadata字段，Stripe会自动将Session的元数据同步到关联的Charge对象中：

stripe.checkout.Session.create(
  payment_method_types=['card'],
  line_items=[...],
  mode='payment',
  success_url='...',
  cancel_url='...',
  client_reference_id='YOUR_ORDER_ID',
  metadata={
    'order_id': 'YOUR_ORDER_ID',  # 同步订单号到metadata
    'additional_info': '你的附加信息'
  }
)

触发charge.refunded事件时，直接从Charge对象的metadata中读取所需信息：

if event['type'] == 'charge.refunded':
  charge = event['data']['object']
  order_id = charge['metadata']['order_id']
  # 执行退款相关业务逻辑

方案2：通过Payment Intent关联到Checkout Session #

如果不想修改metadata结构，可通过Charge关联的Payment Intent反向找到对应的Checkout Session：

1. 从charge.refunded事件的Charge对象中获取payment_intent字段（即Payment Intent的ID）。
2. 调用API检索该Payment Intent，其checkout_session字段对应关联的Checkout Session ID。
3. 检索Checkout Session即可拿到client_reference_id和原metadata：

if event['type'] == 'charge.refunded':
  charge = event['data']['object']
  # 获取关联的Payment Intent
  payment_intent = stripe.PaymentIntent.retrieve(charge['payment_intent'])
  # 获取对应的Checkout Session
  checkout_session = stripe.checkout.Session.retrieve(payment_intent['checkout_session'])
  # 提取目标信息
  order_id = checkout_session['client_reference_id']
  additional_info = checkout_session['metadata']['additional_info']

是否需要存储Charge ID？ #

如果仅需满足退款事件的基础关联需求，上述两种方案都可避免存储Charge ID。但从业务稳定性和可维护性角度，推荐将Charge ID与自有订单关联存储：

• 减少API调用次数，提升WebHook处理效率，避免因API延迟导致的逻辑阻塞。
• 便于后续核对支付、退款明细，故障排查时Charge ID是关键的追踪凭证。
• 可有效应对事件重复触发的场景，通过Charge ID去重，避免重复处理退款。

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