Laravel集成PayPal Advanced Checkout遇capture端点失败的解决方法

以下是针对调用capture.order端点失败的核心排查步骤和修复建议，结合你的代码结构逐一验证：

1. 确认订单状态必须为APPROVED #

PayPal的订单捕获接口仅允许处理**已批准（APPROVED）**的订单，这是最常见的失败原因：

• 前端需确保用户完成支付信息提交后，PayPal按钮的onApprove回调正确触发，且将有效的orderID传给后端。
• 后端捕获前可先调用PayPal的show order接口验证状态：

  // 在PayPalService中添加查询订单状态方法
  public function getOrderStatus($orderId)
  {
      $token = $this->getAccessToken();
      $client = new Client();
      $response = $client->get("{$this->apiUrl}/v2/checkout/orders/{$orderId}", [
          'headers' => [
              'Authorization' => "Bearer {$token}",
          ],
      ]);
      $data = json_decode($response->getBody(), true);
      return $data['status'] ?? null;
  }
  
  // 在PaymentController的captureOrder方法中先验证状态
  public function captureOrder(Request $request)
  {
      $orderId = $request->input('orderId');
      $payPalService = app(PayPalService::class);
      
      $status = $payPalService->getOrderStatus($orderId);
      if ($status !== 'APPROVED') {
          return response()->json(['error' => '订单未完成批准，无法捕获'], 400);
      }
  
      // 后续执行捕获逻辑
  }
  

2. 验证API凭据与环境匹配 #

• 检查.env中的PayPal配置：确保PAYPAL_MODE（sandbox/live）与你的凭据（PAYPAL_CLIENT_ID、PAYPAL_SECRET）对应，沙箱凭据不能用于生产环境，反之亦然。
• 确认PayPalService中的apiUrl是否正确：沙箱为https://api-m.sandbox.paypal.com，生产为https://api-m.paypal.com。

3. 检查请求头与权限令牌有效性 #

• 捕获请求必须携带Content-Type: application/json头，且Authorization中的access token未过期（PayPal令牌有效期约8小时）。
• 确保PayPalService的getAccessToken方法每次都请求新的令牌，而非缓存过长时间：

  public function getAccessToken()
  {
      $client = new Client();
      $response = $client->post("{$this->apiUrl}/v1/oauth2/token", [
          'auth' => [$this->clientId, $this->secret],
          'form_params' => [
              'grant_type' => 'client_credentials',
          ],
      ]);
      $data = json_decode($response->getBody(), true);
      return $data['access_token'];
  }
  

4. 核对订单金额与支付信息一致性 #

• 创建订单时的金额、币种必须与用户实际提交的支付信息完全一致。比如前端表单修改了金额，但后端创建订单时用了固定值，会导致捕获时PayPal拒绝请求。
• 检查createOrder接口中传递给PayPal的purchase_units参数是否正确：

  // 创建订单的请求体示例
  $orderData = [
      'intent' => 'CAPTURE',
      'purchase_units' => [
          [
              'amount' => [
                  'currency_code' => 'USD',
                  'value' => $request->input('amount'), // 必须与前端提交的金额一致
              ],
          ],
      ],
      'payment_source' => [
          'card' => [
              'name' => $request->input('card_name'),
              'number' => $request->input('card_number'),
              'expiry' => $request->input('card_expiry'),
              'security_code' => $request->input('card_cvv'),
          ],
      ],
  ];
  

5. 开启PayPal账户可选功能 #

要允许用户无需PayPal账户支付，需在PayPal商家后台开启对应设置：

1. 登录PayPal商家后台，进入设置 > 网站支付 > 网站偏好设置
2. 找到PayPal账户可选选项，设置为开启
3. 保存设置后，重新测试支付流程

6. 排查详细错误日志 #

在捕获逻辑中添加详细错误日志，直接查看PayPal返回的错误信息：

public function captureOrder($orderId)
{
    $token = $this->getAccessToken();
    $client = new Client();
    try {
        $response = $client->post("{$this->apiUrl}/v2/checkout/orders/{$orderId}/capture", [
            'headers' => [
                'Authorization' => "Bearer {$token}",
                'Content-Type' => 'application/json',
            ],
        ]);
        return json_decode($response->getBody(), true);
    } catch (\Exception $e) {
        // 记录完整错误信息
        \Illuminate\Support\Facades\Log::error('PayPal捕获失败：' . $e->getMessage());
        if ($e->getResponse()) {
            \Illuminate\Support\Facades\Log::error('PayPal错误响应：' . $e->getResponse()->getBody());
        }
        throw $e;
    }
}

常见错误码对应处理：

• ORDER_NOT_APPROVED：订单未完成用户批准，检查前端onApprove逻辑
• INVALID_RESOURCE_ID：订单ID无效或已过期，确认传递的orderID正确
• INSUFFICIENT_PERMISSIONS：API凭据权限不足，检查商家账户是否启用了Advanced Checkout权限

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