PayPal Node SDK两包差异及webhook相关问题

两款SDK核心差异 #

• 维护状态与定位不同
  paypal-rest-sdk是已停止功能迭代的旧版全量REST SDK，早年覆盖PayPal所有REST接口能力（支付、账单、争议、Webhooks、订阅等全业务域），目前官方仅做最低限度的安全补丁维护，明确不推荐新业务接入。
  @paypal/checkout-server-sdk是当前官方主推的结账场景专属轻量SDK，仅聚焦新版标准结账流程的核心接口，没有冗余的其他业务域封装，所有新对接PayPal标准支付的场景都优先推荐使用。
• 适配接口版本不同
  paypal-rest-sdk对接PayPal v1版本REST接口，接口字段、错误码、鉴权逻辑均已过时，和当前新版商户控制台、智能支付按钮的参数规则存在大量不兼容的情况。
  @paypal/checkout-server-sdk原生适配v2版本结账接口，和当前官方最新文档、前端支付按钮的传参规则完全对齐，返回字段、错误处理逻辑更符合当前业务实际。
• 使用体验不同
  旧版SDK依赖冗余、包体积大，内置的access_token自动缓存逻辑存在并发场景下重复请求的已知问题；新版SDK做了场景裁剪，依赖少、体积小，鉴权token刷新逻辑更稳定，支持自定义HTTP客户端适配代理、超时配置等需求。

两款SDK的基础引入方式如下：

// 旧版废弃SDK引入
var paypal = require('paypal-rest-sdk');

// 新版结账SDK引入
const paypal = require('@paypal/checkout-server-sdk');

@paypal/checkout-server-sdk 与Webhooks相关说明 #

• 该SDK不内置任何Webhooks相关能力。因为它是结账流程专属SDK，仅封装了订单创建、订单查询、支付捕获这类需要商户服务端主动发起调用的接口，没有提供Webhook配置、事件签名校验、事件查询这类方法，无法直接基于它实现完整的Webhooks链路。
• 不存在使用该SDK就无需配置Webhooks的说法。只要是生产环境对接PayPal，无论用哪款SDK都必须配置Webhooks：前端跳转的同步回调不可靠，用户付款后主动关闭页面、网络中断、浏览器拦截都会导致同步回调丢失，只有Webhooks推送的服务端事件（比如支付完成、退款完成、争议发起）才是判定业务状态的唯一可信依据。

落地时不需要为了Webhooks能力回退引入废弃的paypal-rest-sdk，只需要自行实现两个核心逻辑即可：

1. 暴露公网可访问的POST接口接收PayPal推送的事件数据
2. 按照官方规则校验事件签名，确认请求确实来自PayPal、未被篡改，避免伪造回调造成资金损失
   签名校验逻辑复杂度不高，既可以自行实现，也可以引入官方单独发布的轻量Webhooks校验工具包，不需要为了这部分能力加载整个旧版全量SDK。

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