React PayPal订阅按钮自定义字段与Webhook数据留存问题

API 探路者

2026-7-18

PayPal订阅Webhook与自定义字段问题解答

核心结论

PayPal Webhook只会保留官方API定义的自定义字段：你代码里的custom_id会被正常带回，但额外添加的userId字段会被PayPal忽略，不会出现在Webhook返回数据中。

原因分析

PayPal的订阅创建API（actions.subscription.create()）仅接受官方文档规定的参数，custom_id是订阅对象的合法属性，用于存储自定义关联数据；而你额外传入的userId不属于API参数列表，PayPal服务器会直接丢弃该字段，自然不会在Webhook事件中返回。

解决方案

把所有需要关联的自定义数据（比如guildId和userId）打包进custom_id字段，推荐用JSON字符串格式：

修正后的代码示例

const createSubscription = (data, actions, guildId, userId) => {
  return actions.subscription.create({
    plan_id: 'PLAN_ID',
    // 将多个自定义字段序列化为JSON字符串
    custom_id: JSON.stringify({ guildId, userId })
  });
};

return (
  <PayPalScriptProvider>
    <PayPalButtons
      // 注意：必须传递PayPal传入的data和actions参数
      createSubscription={(data, actions) => createSubscription(data, actions, guildId, userId)}
      style={{
        shape: 'pill',
        color: 'gold',
        layout: 'horizontal',
        label: 'paypal'
      }}
    />
  </PayPalScriptProvider>
);

注意事项

字段长度限制：custom_id最大支持127个ASCII字符，确保序列化后的JSON字符串不超过这个长度（Discord ID为短字符串/数字，完全满足要求）。
沙箱测试正确姿势：不要用Webhook模拟工具手动生成事件，需完成完整的沙箱订阅流程（用沙箱买家账号完成付款），此时Webhook会返回包含custom_id的真实订阅数据。