Xsolla支付API调用POSTFIELDS错误排查求助

我之前也踩过Xsolla API格式的坑，咱们一步步来搞定这两个问题：

第一个错误：缺少settings.project_id #

你最开始的报错是因为没有以API要求的JSON格式传递参数——Xsolla的支付接口明确要求POST请求主体是JSON字符串，而非默认的表单编码格式。虽然你后来改成了JSON字符串，但紧接着遇到的是数据结构不符合Schema的问题。

第二个错误：purchase.virtual_items.items需要数组而非对象 #

这个错误的核心很明确：你传递的items是单个对象，但API要求它必须是数组，哪怕你只需要提交一个虚拟物品，也要把它放进数组里包裹起来。

调整后的完整PHP cURL示例代码 #

下面是修正后的可参考代码，你可以替换成自己的实际参数：

<?php
// 替换为你的真实配置
$projectId = "你的项目ID";
$accessToken = "你的访问令牌";
$apiEndpoint = "https://api.xsolla.com/payments/v2/projects/{$projectId}/payment-ui";

// 构建完全符合Schema的请求数据
$requestData = [
    "settings" => [
        "project_id" => $projectId,
        "locale" => "zh_CN", // 按需设置语言
        "currency" => "CNY"  // 按需设置货币
    ],
    "purchase" => [
        "virtual_items" => [
            // 重点：items必须是数组，哪怕只有一个元素
            "items" => [
                [
                    "sku" => "你的虚拟物品SKU",
                    "quantity" => 1
                ]
            ]
        ]
    ],
    // 必须填写用户标识信息
    "user" => [
        "id" => [
            "value" => "你的用户唯一ID"
        ]
    ]
];

// 初始化cURL会话
$ch = curl_init($apiEndpoint);

// 设置cURL关键选项
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($requestData, JSON_UNESCAPED_SLASHES));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: Bearer {$accessToken}"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// 执行请求并获取结果
$response = curl_exec($ch);
$httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);

// 关闭会话
curl_close($ch);

// 输出调试信息
echo "HTTP状态码: {$httpStatus}\n";
echo "响应内容: {$response}\n";
?>

额外注意事项 #

• 必填参数不能少：除了上述字段，还要根据你的业务场景补充其他必填参数（比如用户的支付区域等），可以对照Xsolla的官方文档核对。
• JSON编码细节：使用JSON_UNESCAPED_SLASHES可以避免不必要的字符转义，确保生成的JSON完全符合API的格式要求。
• 参数类型严格匹配：所有要求数组的字段，哪怕只有一个元素，都必须用数组包裹，不能直接传单个对象。

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