沙箱环境下MERCHANT.ONBOARDING.COMPLETED webhook未触发的技术问询

针对你遇到的沙箱环境中MERCHANT.ONBOARDING.COMPLETED Webhook未触发，但入驻状态查询显示成功的问题，可以按以下步骤排查和解决：

• 确认Webhook订阅配置准确性
  检查沙箱后台的Webhook订阅列表，确保MERCHANT.ONBOARDING.COMPLETED事件已被正确订阅，状态为ACTIVE。注意事件名称的大小写和格式，PayPal的Webhook事件名严格区分大小写，避免出现拼写错误（比如用下划线代替点分隔符）。

• 验证入驻流程是否完全收尾
  尽管/v1/customer/partners/{partner_merchant_id}/merchant-integrations/{seller_merchant_id}返回了成功状态，但沙箱环境下可能需要完成额外步骤才会触发该Webhook：

  • 模拟关联测试银行账户；
  • 完成身份验证流程（提交沙箱测试身份证明文件）；
  • 填写并提交测试税务信息（部分区域商户需要）。
    可以登录沙箱商户后台，查看是否有未处理的待办任务。

• 检查Webhook接收端点的可用性
  确保接收该Webhook的端点满足PayPal的要求：

  • 端点必须能在15秒内返回200 OK响应，无超时、防火墙或反向代理拦截问题；
  • 如果设置了IP白名单，需将PayPal沙箱的IP段加入白名单；
    可以用Postman模拟发送符合PayPal Webhook格式的POST请求到端点，验证接收能力。

• 查看沙箱Webhook日志
  登录沙箱开发者后台，进入Webhook日志页面：

  • 如果存在MERCHANT.ONBOARDING.COMPLETED事件的记录但标记为失败，根据失败原因（如签名验证失败、端点无响应）修复问题；
  • 如果无该事件记录，说明事件未被触发，需重新确认入驻流程是否遗漏关键步骤。

• 获取更详细的商户状态
  调用/v1/merchant-integrations/{merchant_id}接口（若可用），获取商户入驻的全量状态信息，排查是否存在未完成的子状态项。

• 手动触发测试事件
  在沙箱开发者后台的Webhook管理页面，尝试手动触发MERCHANT.ONBOARDING.COMPLETED事件，验证端点是否能正常接收。若手动触发成功，说明自动触发的流程存在遗漏，需重新走一遍完整的入驻流程。

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