如何解决PayPal Payouts接口返回batch_status为PENDING的交易问题

问题原因与解决步骤 #

你遇到的"batch_status": "PENDING"首先和接口调用的参数配置直接相关，其次还有账户、环境层面的可能原因，按优先级排查如下：

• 调整sync_mode参数实现同步返回结果
  你当前代码中调用create方法时传入的是array('sync_mode' => 'false')，即启用异步处理模式，PayPal异步处理打款请求时会默认返回PENDING状态，该状态为异步模式下的正常返回，不是异常。
  如果是单笔Payout请求，你可以将该参数改为'sync_mode' => 'true'开启同步模式，符合条件的请求会直接返回最终的SUCCESS/FAILED状态，无需等待异步处理。修改代码对应位置如下：

// 原代码
$output = $payouts->create(array('sync_mode' => 'false'), $this->_api_context);
// 修改后
$output = $payouts->create(array('sync_mode' => 'true'), $this->_api_context);

注意：同步模式仅支持单笔Payout请求，且单请求金额不能超过PayPal规定的同步上限（当前为10000USD，不同地区账户可能有差异），超出上限的请求还是会自动进入异步处理流程返回PENDING

• 异步模式下的PENDING处理方案
  如果你必须使用异步模式处理打款，可通过两种方式获取最终状态：

  • 轮询Payout详情接口：使用接口返回的batch_id调用Payout::get($batch_id, $api_context)方法，主动查询打款批次的最终状态，建议轮询间隔设置为30秒以上，避免触发接口限流
  • 配置Payout相关Webhook：在PayPal开发者后台配置PAYMENT.PAYOUTS-ITEM.SUCCEEDED、PAYMENT.PAYOUTS-ITEM.FAILED等事件的Webhook地址，PayPal处理完成后会主动推送状态到你的服务端

• 其他可能导致持续PENDING的排查点

  • 检查你的PayPal账户是否已经开通Payout权限：默认新的开发者账户或者企业账户没有开启Payout功能，需要在账户后台提交申请开通后才能正常处理打款，未开通权限的请求会一直处于PENDING最终返回失败
  • 若使用沙盒环境测试：检查沙盒收款方账户是否完成邮箱验证，未验证的邮箱对应的收款账户收到打款时会处于PENDING状态，需要手动登录沙盒账户确认收款，也可以在沙盒账户设置中开启自动接收所有款项
  • 检查打款币种和账户币种是否匹配：如果你的PayPal账户没有开通对应币种的余额，打款请求会进入审核流程导致PENDING，建议开通对应币种账户或者开启自动货币兑换功能

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