PHP PayPal 安全集成：实现基于服务器端的订单创建与捕获-php教程-PHP中文网

PHP PayPal 安全集成：实现基于服务器端的订单创建与捕获

本教程旨在指导开发者如何安全、高效地集成 paypal 支付功能，避免使用不安全的 get 请求和不完整的 post 方法。文章将详细阐述 paypal 标准支付流程中服务器端“创建订单”和“捕获订单”的两个关键步骤，并结合官方 checkout-php-sdk 提供实现思路。通过将核心支付逻辑迁移至服务器，并与前端审批流程协同，确保交易数据的完整性与安全性，最终实现一个健壮的在线支付系统。

在构建在线支付系统时，安全性是首要考虑因素。传统的通过 GET 请求将所有交易参数暴露在 URL 中，或直接在客户端发起不完整的 POST 请求，都可能导致数据篡改、支付失败或安全漏洞。PayPal 官方推荐的集成方式是采用服务器端 API 调用结合前端审批流程，以确保交易的完整性和安全性。

为什么避免 GET 请求和不完整的 POST 方法？

原始问题中提供的第一个 PHP 代码片段通过 http_build_query 构建一个 GET 请求 URL，将所有订单信息（如商品名称、金额、收件人邮箱等）作为查询参数传递。这种方式存在严重的安全隐患：

数据篡改风险： 恶意用户可以通过代理或直接修改 URL 参数来更改商品价格、数量甚至收款方邮箱，从而导致商家损失。
信息泄露： 敏感交易信息暴露在 URL 中，可能被日志记录或浏览器历史记录保存。

第二个代码片段尝试使用 cURL 发起 POST 请求到 PayPal API v2，但仅创建了订单而未完成支付捕获。这导致用户在 PayPal 页面批准支付后，款项并未实际转移，订单状态仍处于未支付。

正确的 PayPal 集成策略应遵循其标准支付流程，将核心交易逻辑（订单创建和支付捕获）放在服务器端处理。

立即学习“PHP免费学习笔记（深入）”；

PayPal 标准支付集成核心：服务器端 API 调用

PayPal 标准支付要求在服务器端实现两个关键的 API 调用：

创建订单 (Create Order)： 在用户确认支付前，在服务器端向 PayPal 发起请求，创建一个待支付的订单。
捕获订单 (Capture Order)： 在用户通过 PayPal 界面批准支付后，服务器端再次向 PayPal 发起请求，捕获该订单的款项，完成实际的资金转移。

这两个步骤通过 PayPal 官方提供的 SDK（例如 PHP 的 Checkout-PHP-SDK）来实现，并与前端的 JavaScript SDK 协同工作。

1. 环境准备与 SDK 安装

首先，确保您的 PHP 环境已配置妥当，并安装 PayPal Checkout-PHP-SDK。通过 Composer 进行安装：

composer require paypal/paypal-checkout-sdk

登录后复制

接着，您需要配置 PayPal API 凭据（Client ID 和 Client Secret）。这些凭据可以在您的 PayPal 开发者账户中获取，并根据环境（Sandbox 或 Live）进行切换。

// 示例：PayPalClient.php (用于获取客户端实例)
<?php

namespace App\Services;

use PayPalCheckoutSdk\Core\PayPalHttpClient;
use PayPalCheckoutSdk\Core\SandboxEnvironment; // 或 LiveEnvironment

class PayPalClient
{
    public static function client(): PayPalHttpClient
    {
        // 根据实际环境选择
        $clientId = env('PAYPAL_CLIENT_ID');
        $clientSecret = env('PAYPAL_CLIENT_SECRET');
        $environment = new SandboxEnvironment($clientId, $clientSecret); // 生产环境使用 LiveEnvironment

        return new PayPalHttpClient($environment);
    }
}

登录后复制

2. 实现“创建订单”服务器端路由

这个路由负责初始化一个 PayPal 订单，并将订单 ID 和批准链接返回给前端。前端将使用这些信息引导用户到 PayPal 完成审批。

功能要点：

集简云

软件集成平台，快速建立企业自动化与智能化

查看详情

接收来自前端的商品信息或订单详情。
使用 PayPal Checkout-PHP-SDK 的 OrdersCreateRequest 构建请求。
指定 intent 为 CAPTURE（表示直接捕获支付）或 AUTHORIZE（表示先授权后捕获）。
包含 purchase_units（购买单元）和 application_context（应用程序上下文，包含返回/取消 URL 等）。
将 PayPal 返回的订单 ID 和审批链接以 JSON 格式返回给前端。

示例代码：

// app/Http/Controllers/PayPalController.php (或您的支付控制器)
<?php

namespace App\Http\Controllers;

use App\Services\PayPalClient; // 假设您已定义 PayPalClient 服务
use Illuminate\Http\Request;
use PayPalCheckoutSdk\Orders\OrdersCreateRequest;

class PayPalController extends Controller
{
    public function createOrder(Request $request)
    {
        // 1. 从请求中获取订单数据 (例如：购物车商品、总金额等)
        // 实际应用中，这些数据应从您的数据库或会话中获取，以防止客户端篡改
        $items = [
            // ... 您的商品列表 ...
            [
                'name' => '商品A',
                'quantity' => '1',
                'unit_amount' => [
                    'currency_code' => 'USD',
                    'value' => '10.00'
                ]
            ]
        ];
        $totalAmount = '10.00'; // 根据商品计算总金额

        $request = new OrdersCreateRequest();
        $request->prefer('return=representation'); // 请求完整的响应体
        $request->body = [
            'intent' => 'CAPTURE', // 意图：直接捕获支付
            'purchase_units' => [[
                'amount' => [
                    'currency_code' => 'USD',
                    'value' => $totalAmount,
                    'breakdown' => [
                        'item_total' => [
                            'currency_code' => 'USD',
                            'value' => $totalAmount
                        ]
                    ]
                ],
                'items' => $items,
            ]],
            'application_context' => [
                'return_url' => route('paypal.success'), // 支付成功后的回调URL
                'cancel_url' => route('paypal.cancel'), // 支付取消后的回调URL
                'brand_name' => '您的商店名称',
                'shipping_preference' => 'NO_SHIPPING', // 如果不需要收货地址
                'user_action' => 'PAY_NOW', // 用户在PayPal页面上看到“立即支付”按钮
            ]
        ];

        try {
            $client = PayPalClient::client(); // 获取 PayPal 客户端实例
            $response = $client->execute($request);

            // 返回订单ID和审批链接给前端
            return response()->json([
                'id' => $response->result->id,
                'links' => $response->result->links
            ]);
        } catch (\Exception $e) {
            // 错误处理：记录日志、返回错误信息
            return response()->json(['error' => $e->getMessage()], 500);
        }
    }
}

登录后复制

3. 实现“捕获订单”服务器端路由

这个路由在用户完成 PayPal 审批后被前端调用，用于实际执行资金捕获。这是支付流程中至关重要的一步，确保资金从买家账户转移到卖家账户。

功能要点：

接收前端传递的 orderID。
使用 PayPal Checkout-PHP-SDK 的 OrdersCaptureRequest 构建请求。
在成功捕获后，立即执行业务逻辑：
- 存储交易详情： 将 PayPal 返回的交易 ID（purchase_units[0].payments.captures[0].id）存储到您的数据库中。这是唯一标识 PayPal 交易的关键信息。
- 更新订单状态： 将您的内部订单状态从“待支付”更新为“已支付”或“已完成”。
- 执行后续操作： 如发送订单确认邮件、减少库存、生成发货单等。
将捕获结果以 JSON 格式返回给前端。

示例代码：

// app/Http/Controllers/PayPalController.php (或您的支付控制器)
<?php

namespace App\Http\Controllers;

use App\Services\PayPalClient;
use Illuminate\Http\Request;
use PayPalCheckoutSdk\Orders\OrdersCaptureRequest;

class PayPalController extends Controller
{
    public function captureOrder(Request $request, $orderId)
    {
        $request = new OrdersCaptureRequest($orderId);
        $request->prefer('return=representation');

        try {
            $client = PayPalClient::client();
            $response = $client->execute($request);

            // 2. 支付成功，处理业务逻辑
            if ($response->result->status === 'COMPLETED') {
                $captureId = $response->result->purchase_units[0]->payments->captures[0]->id;

                // 存储 $captureId 到数据库
                // 例如：Order::where('paypal_order_id', $orderId)->update(['status' => 'paid', 'paypal_capture_id' => $captureId]);

                // 更新订单状态
                // 发送确认邮件
                // 减少库存
                // ...

                return response()->json([
                    'status' => 'COMPLETED',
                    'capture_id' => $captureId,
                    'message' => '支付成功，订单已完成处理。'
                ]);
            } else {
                // 支付状态不是 COMPLETED，可能需要进一步处理（例如：PENDING, DENIED 等）
                return response()->json([
                    'status' => $response->result->status,
                    'message' => '支付未完成或处于待处理状态。'
                ], 400);
            }
        } catch (\Exception $e) {
            // 错误处理：记录日志，可能需要退款或记录失败信息
            return response()->json(['error' => $e->getMessage()], 500);
        }
    }
}

登录后复制

4. 前端集成（PayPal JavaScript SDK）

前端负责渲染 PayPal 支付按钮，并与上述两个服务器端路由进行交互。

主要步骤：

引入 PayPal JavaScript SDK： 在您的页面中加载 PayPal JS SDK。
渲染 PayPal 按钮： 使用 paypal.Buttons() 方法渲染支付按钮。
createOrder 回调： 当用户点击 PayPal 按钮时，调用服务器端的“创建订单”路由，并将返回的 orderID 传递给 PayPal JS SDK。
onApprove 回调： 当用户在 PayPal 页面上批准支付后，PayPal JS SDK 会触发 onApprove 回调，并提供 orderID。此时，调用服务器端的“捕获订单”路由，完成支付。
错误处理： 实现 onCancel 和 onError 回调，处理用户取消支付或发生错误的情况。

示例 HTML/JavaScript：

<!DOCTYPE html>
<html>
<head>
    <title>PayPal Checkout</title>
</head>
<body>
    <h1>商品结算</h1>
    <div id="paypal-button-container"></div>

    <!-- 引入 PayPal JavaScript SDK -->
    <!-- 替换 YOUR_CLIENT_ID 为您的 PayPal 客户端 ID -->
    <!-- `currency` 参数根据您的业务需求设置 -->
    <script src="https://www.paypal.com/sdk/js?client-id=YOUR_PAYPAL_CLIENT_ID&currency=USD"></script>

    <script>
        paypal.Buttons({
            // 设置创建订单的回调函数
            createOrder: function(data, actions) {
                // 调用您的服务器端 "创建订单" 路由
                return fetch('/api/paypal/create-order', { // 替换为您的实际路由
                    method: 'post',
                    headers: {
                        'Content-Type': 'application/json',
                        'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').getAttribute('content') // 如果使用 Laravel
                    },
                    body: JSON.stringify({
                        // 可以在这里传递一些客户端数据，但核心订单详情应在服务器端生成
                        // 例如：'cartId': 'user_cart_id'
                    })
                })
                .then(function(response) {
                    if (!response.ok) {
                        throw new Error('Failed to create PayPal order');
                    }
                    return response.json();
                })
                .then(function(order) {
                    return order.id; // 返回 PayPal 订单 ID
                })
                .catch(function(error) {
                    console.error('Error creating PayPal order:', error);
                    alert('创建订单失败，请稍后再试。');
                    // 可以在这里显示更友好的错误消息给用户
                });
            },

            // 设置订单批准后的回调函数
            onApprove: function(data, actions) {
                // 调用您的服务器端 "捕获订单" 路由
                return fetch(`/api/paypal/capture-order/${data.orderID}`, { // 替换为您的实际路由
                    method: 'post',
                    headers: {
                        'Content-Type': 'application/json',
                        'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').getAttribute('content') // 如果使用 Laravel
                    }
                })
                .then(function(response) {
                    if (!response.ok) {
                        throw new Error('Failed to capture PayPal order');
                    }
                    return response.json();
                })
                .then(function(details) {
                    if (details.status === 'COMPLETED') {
                        alert('支付成功！交易ID: ' + details.capture_id);
                        // 重定向到成功页面或更新 UI
                        window.location.href = '/order-success?orderId=' + data.orderID;
                    } else {
                        alert('支付未完成或失败。状态: ' + details.status);
                        // 处理非完成状态
                    }
                })
                .catch(function(error) {
                    console.error('Error capturing PayPal order:', error);
                    alert('支付捕获失败，请联系客服。');
                });
            },

            // 设置取消支付的回调函数
            onCancel: function(data) {
                console.log('Payment cancelled by user', data);
                alert('支付已取消。');
                // 重定向到取消页面或更新 UI
            },

            // 设置支付错误的回调函数
            onError: function(err) {
                console.error('Payment error', err);
                alert('支付过程中发生错误，请稍后再试。');
                // 重定向到错误页面或更新 UI
            }
        }).render('#paypal-button-container'); // 将按钮渲染到指定的容器
    </script>
</body>
</html>

登录后复制

注意事项与最佳实践

数据源权威性： 始终在服务器端获取和验证商品价格、数量等订单核心数据，而不是依赖客户端提交的数据，以防止欺诈。
错误处理： 无论服务器端还是前端，都应有健壮的错误处理机制。服务器端捕获异常并记录日志，前端向用户提供清晰的反馈。
幂等性： 确保“捕获订单”操作是幂等的。如果由于网络问题重复调用，PayPal 会防止重复扣款，但您的系统也应能正确处理这种情况。
Webhook/IPN： 考虑使用 PayPal 的 Webhook 或 IPN (Instant Payment Notification) 来接收异步支付通知。这可以作为支付状态更新的补充或备用机制，特别是在用户关闭浏览器或网络中断时。
退款与争议： 熟悉 PayPal 的退款 API 和争议处理流程，为售后服务做好准备。
安全存储凭据： PayPal API 凭据（Client ID 和 Secret）应安全存储，例如使用环境变量或密钥管理服务，绝不能硬编码在代码中或暴露在客户端。
测试： 在沙盒 (Sandbox) 环境中进行充分测试，确保所有流程（包括成功、取消、错误）都能按预期工作，然后再部署到生产环境。

总结

通过遵循 PayPal 官方推荐的服务器端集成模式，即实现“创建订单”和“捕获订单”两个核心路由，并与 PayPal JavaScript SDK 协同，您可以构建一个既安全又用户友好的在线支付系统。这种方法将敏感的交易逻辑和数据处理保留在服务器端，有效规避了客户端请求可能带来的安全风险，并确保了支付流程的完整性和可靠性。务必利用官方 SDK 简化开发，并始终将安全性和数据完整性放在首位。

以上就是PHP PayPal 安全集成：实现基于服务器端的订单创建与捕获的详细内容，更多请关注php中文网其它相关文章！