使用NestJS+HTML开发Paddle沙箱支付时的三类问题求助

1. 支付普通产品时通过Webhook获取checkout_id #

Paddle旧版集成中，一次性产品的sale_completed Webhook事件本身不会返回checkout_id，这是订阅与一次性产品的设计差异（订阅类产品Webhook默认携带该字段）。可通过两种方式解决：

• 前端关联存储：在前端Checkout.Complete事件触发时，能直接拿到checkout_id，将该ID与Webhook返回的p_order_id关联存储到你的数据库，后续通过订单ID反向查询checkout_id即可。
• 切换到Paddle Checkout v2：升级到Paddle.js v2版本，使用新的Checkout API，此时所有支付完成的Webhook事件（checkout.completed）都会统一返回checkout_id，无论订阅还是一次性产品。沙箱环境完全支持v2集成，调整后的前端代码示例：

  // Paddle.js v2 沙箱配置
  Paddle.Environment.set('sandbox');
  Paddle.Initialize({
    token: '你的沙箱API令牌'
  });
  
  Paddle.Checkout.open({
    items: [{
      priceId: '你的一次性产品价格ID'
    }],
    allowQuantity: true,
    passthrough: { userId: 9 }
  });
  

2. 解决quantity选择3但Webhook显示1且被调用3次的问题 #

这是Paddle旧版一次性产品的默认行为：多件一次性产品会被拆分为多个独立订单，每个订单对应1件商品，因此Webhook会触发多次。解决方法：

• 启用沙箱后台的**多商品订单（Multi-Item Orders）**功能：在「Settings > Checkout」中找到该选项并开启，开启后多件一次性产品会合并为一个订单，Webhook仅触发一次，quantity字段会显示实际购买数量。
• 直接切换到Paddle Checkout v2：v2默认支持多件商品合并为单个订单，无需额外配置。

3. 修复eventCallback函数未触发的问题 #

结合代码和常见故障点，从以下方向排查修复：

• 确保Paddle.js加载完成：将代码包裹在页面加载事件中，避免Paddle.js未加载完成就执行配置：

  window.addEventListener('load', function() {
    Paddle.Environment.set('sandbox');
    Paddle.Setup({ 
      vendor: '你的沙箱Vendor ID',
      eventCallback: function (data) {
        console.log(data.event, data.eventData);
      }
    });
    Paddle.Checkout.open({ 
      product: '你的沙箱产品ID',
      allowQuantity:true,
      passthrough:{ userId:9 } 
    });
  });
  

• 检查配置与语法错误：确认代码中xxxx已替换为实际的沙箱Vendor ID和产品ID，打开浏览器控制台查看是否有加载失败、参数格式错误等报错。
• 切换到v2事件监听：旧版eventCallback存在兼容性问题，改用Paddle.js v2的事件监听方式更稳定：

  Paddle.Events.on('checkout.loaded', function(data) {
    console.log('Checkout加载完成', data);
  });
  Paddle.Events.on('checkout.completed', function(data) {
    console.log('支付完成', data);
  });
  

• 验证沙箱环境配置：确认使用的是沙箱专属的Vendor ID和产品ID，不要混用生产环境的配置信息。

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