如何在 PayPal Orders API 中正确设置商品购买数量-php教程-PHP中文网

如何在 PayPal Orders API 中正确设置商品购买数量

本文详解在 Laravel 中使用 PayPal Orders API 创建订单时，如何通过 items 数组正确配置商品数量（quantity），避免因结构错误导致的“Expected an order id to be passed”等前端报错。

本文详解在 laravel 中使用 paypal orders api 创建订单时，如何通过 items 数组正确配置商品数量（quantity），避免因结构错误导致的“expected an order id to be passed”等前端报错。

在 PayPal Orders API 中，quantity 并非直接设于 purchase_units 顶层，而是必须嵌套在规范的 items 数组结构内——且该 items 字段本身必须是一个包含一个或多个商品对象的数组（即二维数组），而非单个商品对象（一维结构）。你遇到的 Uncaught Error: Expected an order id to be passed 错误，表面看是前端 SDK 缺少 order ID，但根本原因在于后端创建订单时请求体格式非法，导致 createOrder() 调用失败并返回空/无效响应，进而使前端无法获取有效 order ID。

以下是修正后的完整示例（适配 Laravel + srmklive/laravel-paypal 包）：

public function create(Request $request)
{
    $provider = \PayPal::setProvider();
    $provider->setApiCredentials(config('paypal'));
    $token = $provider->getAccessToken();
    $provider->setAccessToken($token);

    $unitPrice = '1.50';
    $quantity = 5;
    $totalAmount = bcmul($unitPrice, (string)$quantity, 2); // 精确计算：1.50 × 5 = 7.50

    $order = $provider->createOrder([
        'intent' => 'CAPTURE',
        'purchase_units' => [
            [
                'amount' => [
                    'currency_code' => 'EUR',
                    'value' => $totalAmount,
                    'breakdown' => [
                        'item_total' => [
                            'currency_code' => 'EUR',
                            'value' => $totalAmount
                        ]
                    ]
                ],
                'items' => [
                    [
                        'name' => 'Photo Print',
                        'quantity' => (string)$quantity,
                        'unit_amount' => [
                            'currency_code' => 'EUR',
                            'value' => $unitPrice
                        ],
                        'category' => 'DIGITAL_GOODS' // 可选，但推荐明确分类
                    ]
                ]
            ]
        ]
    ]);

    return response()->json($order);
}

✅ 关键修正点说明：

items 必须是数组套数组：'items' => [[ ...item object... ]]，而非 'items' => [ ...item object... ]；
amount.value 应等于 item_total.value（即 unit_amount × quantity 的总和），二者必须严格一致，否则 PayPal 会校验失败；
建议显式添加 breakdown.item_total，增强结构清晰性与兼容性；
使用 bcmul() 进行高精度价格计算，避免浮点数误差；
quantity 推荐转为字符串（PayPal API 要求），但整数亦可接受。

⚠️ 注意事项：

PayPal 不允许在 purchase_units 中省略 items 却设置 item_total；若需展示数量，items 为必填项；
每个 purchase_unit 可包含多个 items（如多商品），但单商品场景下仍需包裹为数组；
前端 JS SDK 初始化时，务必确保后端返回的 order.id 非空且有效——仅当上述结构正确时，createOrder() 才会成功返回含 id 的订单对象。