Stripe Webhook集成问题：调用customers.retrieve时customer参数为null报错

问题详情 #

Stripe Webhook流程能正常返回200状态码，但调用stripe.customers.retrieve()时触发错误：

Stripe: Argument "customer" must be a string, but got: null (on API request to GET /v1/customers/{customer})

相关代码片段：

// Handle the event
if(eventType==="checkout.session.completed"){ 
  stripe.customers.retrieve(data.customer) 
    .then((customer)=>{ 
      //console.log(customer); 
      //console.log("data",data); 
      createOrders(customer,data) 
    }).catch((err)=>console.log(err.message)) 
}

// Return a 200 response to acknowledge receipt of the event
res.send().end();
});

原因分析 #

报错核心是data.customer的值为null，而stripe.customers.retrieve()必须传入有效的字符串类型客户ID。这种情况大多出现在**访客结账（Guest Checkout）**场景：用户未创建Stripe客户账户就完成支付，此时checkout.session对象中的customer字段会返回null。

解决方案 #

1. 增加非空校验，兼容访客结账 #

在调用retrieve方法前先判断data.customer是否存在，不存在则直接从Checkout Session的customer_details字段提取客户信息：

if(eventType==="checkout.session.completed"){ 
  if(data.customer){
    // 有客户ID时，查询完整客户信息
    stripe.customers.retrieve(data.customer) 
      .then((customer)=>{ 
        createOrders(customer, data) 
      }).catch((err)=>console.error('客户查询失败:', err)) 
  } else {
    // 访客结账场景，使用session中的客户详情
    const guestCustomer = {
      email: data.customer_details?.email,
      name: data.customer_details?.name,
      phone: data.customer_details?.phone
      // 根据业务需求添加其他字段
    };
    createOrders(guestCustomer, data);
  }
}

2. 强制创建客户账户（可选） #

如果业务要求必须关联Stripe客户账户，可以在创建Checkout Session时设置customer_creation: "required"，强制用户生成客户账户，确保data.customer不为空：

// 创建Checkout Session的示例代码
const session = await stripe.checkout.sessions.create({
  payment_method_types: ['card'],
  line_items: [/* 你的商品项 */],
  mode: 'payment',
  success_url: 'https://your-domain.com/success',
  cancel_url: 'https://your-domain.com/cancel',
  customer_creation: "required" // 强制创建客户
});

3. 优化错误处理 #

在catch块中添加更详细的日志，便于后续排查问题：

.catch((err)=>{
  console.error('Stripe API调用错误:', err);
  // 可选：将错误信息上报到监控系统
})

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