深入理解 PayPal Payouts 的“PENDING”状态及其解决方案

理解 PayPal Payouts 的“PENDING”状态

在使用PayPal Payouts功能进行批量支付时，开发者可能会观察到API响应中的batch_status字段显示为“PENDING”。这并非异常情况，而是PayPal Payouts批处理机制的正常表现。PayPal Payouts交易通常以批次形式运行，当您提交一个支付请求批次时，该批次的初始状态通常会显示为“PENDING”，这意味着该批次已被PayPal系统接收并正在处理中。

更重要的是，batch_status为“PENDING”并不意味着批次中的所有单个支付项都处于挂起状态。批次状态反映的是整个批次的宏观进展，而每个批次内部的单个支付项（Payout Item）都有其独立的状态。因此，在处理PPOut交易时，我们应将关注点从整体批次状态转移到批次内各个支付项的具体状态。

导致单个支付项“PENDING”的常见原因

尽管批次状态为“PENDING”是正常的，但如果批次中的某个或多个单个支付项长时间保持“PENDING”状态，通常是由以下原因造成的：

1. 收款方PayPal账户邮箱未确认： 这是最常见也是最主要的原因。当向一个PayPal账户发送支付时，如果该账户的注册邮箱尚未经过确认，PayPal会暂时挂起这笔支付。收款方需要登录其PayPal账户并完成邮箱确认，或者如果该邮箱尚未注册PayPal账户，则需要使用该邮箱地址注册一个PayPal账户并确认邮箱，才能接收这笔款项。
2. 收款方未创建PayPal账户： 如果支付被发送到一个尚未注册PayPal的邮箱地址，收款方需要在30天内使用该邮箱地址注册一个PayPal账户并确认邮箱，才能接收款项。
3. 其他潜在原因： 虽然不常见，但某些情况下，收款方账户可能存在限制、交易额度问题或PayPal内部的风险审查，也可能导致支付挂起。

处理期限与自动退款机制： PayPal为收款方提供了30天的期限来处理挂起的支付。在此期间，PayPal会向收款方发送提醒邮件，敦促他们完成必要的账户操作（如确认邮箱或创建账户）。如果30天内收款方未能完成这些操作，该笔支付将自动被PayPal系统退回给付款方。

如何处理和监控“PENDING”状态

为了有效管理PayPal Payouts的“PENDING”状态，开发者应采取以下策略：

1. 查询单个支付项状态： 在您的应用程序中，不应仅仅依赖批次状态。在创建批次后，应记录批次的batch_id，并定期或根据需要通过PayPal Payouts API查询该批次的详细信息，以获取每个单个支付项的最新状态。

   // 假设您已经成功创建了Payout并获得了批次ID
   $payoutBatchId = $output->getBatchHeader()->getPayoutBatchId();
   
   // 创建一个Payout对象用于查询
   $payout = new \PayPal\Api\Payout();
   
   try {
       // 使用批次ID查询Payout批次详情
       $payoutBatch = $payout->get($payoutBatchId, $this->_api_context);
   
       // 遍历批次中的每个支付项，检查其状态
       foreach ($payoutBatch->getItems() as $payoutItem) {
           $transactionStatus = $payoutItem->getTransactionStatus();
           $receiverEmail = $payoutItem->getReceiver();
           echo "Receiver: " . $receiverEmail . ", Status: " . $transactionStatus . "\n";
           // 根据transactionStatus进行后续处理，例如更新数据库、发送通知等
           if ($transactionStatus === 'PENDING') {
               // 可以进一步检查pending_reason
               $pendingReason = $payoutItem->getPendingReason();
               echo "Pending Reason: " . $pendingReason . "\n";
               // 建议通知收款方确认其PayPal邮箱
           }
       }
   } catch (\Exception $ex) {
       // 处理查询异常
       dd($ex);
   }

   登录后复制

   通过这种方式，您可以获取到每个支付项的transaction_status，例如“SUCCESS”、“PENDING”、“RETURNED”等，以及可能的pending_reason。

   

   钉钉 AI 助理

   钉钉AI助理汇集了钉钉AI产品能力，帮助企业迈入智能新时代。

   21

   查看详情

2. 实现状态跟踪与通知机制： 在您的系统数据库中记录每个支付项的transaction_id和当前状态。当支付项状态为“PENDING”时，建议：

   • 通知收款方： 通过邮件或其他方式主动告知收款方，有一笔款项正在等待接收，并指导他们登录PayPal账户确认邮箱。
   • 定期重试/查询： 对于长时间挂起的支付，可以设置定时任务，定期查询其状态，以便及时发现状态变更（如变为“SUCCESS”或“RETURNED”）。
   • 处理退款： 如果支付最终被“RETURNED”（退回），您的系统应能识别此状态，并将款项退回到付款方账户或进行其他适当的处理。

示例代码分析与最佳实践

以下是您提供的PayPal Payouts创建单个支付的PHP示例代码：

public function payoutWithPaypal()
{
    $request_amount = session()->get('request_amount');
    $transaction_id = session()->get('transaction_id'); // 注意：此处的transaction_id可能指您内部的订单ID
    $receiver_email = session()->get('receiver_email');

    $payouts = new \PayPal\Api\Payout();
    $senderBatchHeader = new \PayPal\Api\PayoutSenderBatchHeader();
    $senderBatchHeader->setSenderBatchId(uniqid())->setEmailSubject("You have a Payout!"); // 生成唯一的批次ID
    $senderItem = new \PayPal\Api\PayoutItem();
    $senderItem->setRecipientType('Email')
                ->setNote('Thanks for your patronage!')
                ->setReceiver($receiver_email)
                ->setSenderItemId("001") // 您内部的支付项ID
                ->setAmount(new \PayPal\Api\Currency('{
                            "value":"'.$request_amount.'",
                            "currency":"USD"
                        }'));

    $payouts->setSenderBatchHeader($senderBatchHeader)->addItem($senderItem);
    $request = clone $payouts; // 备份请求对象，虽然在此处不是必须的

    try {
        $output = $payouts->create(array('sync_mode' => 'false'), $this->_api_context);
        // 在此处，您会得到一个包含 "batch_status": "PENDING" 的响应
        // 关键在于获取并存储 $output->getBatchHeader()->getPayoutBatchId()
        // 以便后续查询单个支付项的状态

    } catch (\Exception $ex) {
         dd($ex); // 错误处理
    }

    return $output;
}

代码分析： 您的这段代码在逻辑上是正确的，它成功地构建了一个PayPal Payouts请求并将其发送出去。当您收到"batch_status": "PENDING"的响应时，这表示您的请求已被PayPal成功接收并进入处理队列，这并不是代码层面的错误。sync_mode设置为false表示您希望以异步方式处理批次，这也是推荐的做法，因为它允许PayPal在后台处理交易，而您的应用程序可以立即响应。

最佳实践建议：

1. 保存批次ID： 在$output = $payouts-youjiankuohaophpcncreate(...)成功执行后，务必从$output对象中提取并保存PayoutBatchId（例如：$output->getBatchHeader()->getPayoutBatchId()）。这是您后续查询该批次及其中单个支付项状态的唯一标识。
2. 异步处理与Webhook： 对于生产环境，强烈建议结合PayPal Webhook机制。当支付项状态发生变化时（如从“PENDING”变为“SUCCESS”或“RETURNED”），PayPal会向您预设的Webhook URL发送通知。这样，您的系统可以实时接收状态更新，而无需频繁地主动查询。
3. 完善错误处理： catch (\Exception $ex)块中，除了dd($ex)外，应实现更健壮的错误日志记录机制，以便在生产环境中追踪和调试问题。
4. 内部事务ID： setSenderItemId("001")这个字段非常重要，它允许您将PayPal的支付项与您内部的订单或事务关联起来。确保这个ID是您系统内部唯一的，以便于匹配和跟踪。

总结与注意事项

PayPal Payouts的“PENDING”状态是批处理机制的固有特性，通常不代表API调用失败。关键在于理解其背后的含义：

• 批次状态“PENDING”是正常起点。
• 单个支付项的状态才是核心。
• 未确认的收款方邮箱是导致长期“PENDING”的最常见原因。

作为开发者，您的任务是构建一个能够查询、跟踪和响应这些状态变化的系统。通过保存PayoutBatchId、定期查询支付项状态（或利用Webhook）、并主动引导收款方确认其PayPal账户邮箱，您可以有效地管理PayPal Payouts交易，确保资金顺利到达收款方，并及时处理任何挂起或退回的情况。

以上就是深入理解 PayPal Payouts 的“PENDING”状态及其解决方案的详细内容，更多请关注php中文网其它相关文章！