X-Cart 使用 directone 支付时出现模糊错误

结论

Response: System Error 通常是 X-Cart 向用户展示的 DirectOne 通用错误。仅凭这条信息无法确定具体原因。应先检查 X-Cart 的支付日志和 PHP 错误日志，再核对 DirectOne 商户配置、测试与生产环境、服务器网络连接以及 TLS 支持情况。

如果日志确认 DirectOne 返回了 System Error，却没有提供更具体的响应码，需要把交易时间、商户号和网关交易编号交给 DirectOne 技术支持，请对方查询服务端日志。

先查看 X-Cart 日志

日志位置取决于 X-Cart 的大版本和具体发行版。

常见的 X-Cart 4.x 通常将日志保存在安装目录下：

<xcart_dir>/var/log/

优先查看文件名中包含以下关键词的日志：

payment
php
error

文件名可能带有日期，例如：

x-errors_php-YYYYMMDD.php
x-errors_payments-YYYYMMDD.php

某些旧版本使用不同的命名方式。遇到这种情况，可以直接查看 var/log 中哪些文件在结账失败前后有过更新。

X-Cart 5.x 的日志通常也在安装目录的 var/log 中，但其日志结构和文件名与 4.x 不同，不能直接照搬 4.x 支付模块的调试方法。

如果有终端权限，可以按照失败时间或错误文本搜索日志：

grep -RniE "DirectOne|System Error|declined|payment" /path/to/xcart/var/log

还要检查 Web 服务器和 PHP 日志。常见位置包括：

/var/log/apache2/error.log
/var/log/httpd/error_log
/var/log/nginx/error.log

PHP-FPM 日志的位置取决于服务器配置，无法只根据 X-Cart 版本判断。

建议的排查顺序

1. 确认错误来自哪一层

先根据日志判断属于哪种情况：

• X-Cart 在发送请求前出现 PHP 错误；
• 服务器无法连接 DirectOne；
• DirectOne 返回 HTTP 错误页面或空响应；
• DirectOne 正常收到请求，但返回业务错误；
• DirectOne 已经扣款，但 X-Cart 无法验证回调或解析响应。

如果日志中的原始响应就是 System Error，错误很可能出在网关一侧。如果日志中只有 PHP warning、连接超时或证书错误，应先修复服务器环境。

2. 核对 DirectOne 配置

重新检查 X-Cart 后台的支付方式配置，特别是以下项目：

• Merchant ID、用户名及其他商户凭证；
• 测试账号是否连接测试环境；
• 正式账号是否连接生产环境；
• 订单币种是否在商户账户支持的范围内；
• 商户账户是否已启用当前交易类型；
• 返回地址和服务器回调地址是否正确；
• DirectOne 后台是否设置了来源 IP 限制；
• 复制凭证时是否带入了空格或换行。

不要参照旧教程自行修改网关地址。DirectOne 是较早期的支付集成，其接口地址和账户状态可能已经变化，应以商户后台或支付服务商提供的资料为准。

3. 检查服务器通信能力

支付模块通常需要由服务器主动连接网关，因此要确认：

• PHP 的 cURL 扩展可以使用；
• DNS 能够解析网关域名；
• 防火墙允许出站 HTTPS 连接；
• CA 证书包有效；
• PHP、cURL 和 OpenSSL 支持网关要求的 TLS 版本；
• 服务器时间准确。

可以先检查运行环境：

php -m | grep -i curl
php -i | grep -E "cURL support|OpenSSL"
curl --version

确认支付模块代码或官方配置中的真实网关地址后，可以测试 HTTPS 握手：

curl -Iv https://confirmed-directone-endpoint.example/

不要使用猜测的域名或接口地址。如果测试结果包含 SSL certificate problem、Could not resolve host 或 Connection timed out，说明问题发生在 X-Cart 发出交易请求之前。

4. 检查金额和字段格式

旧支付接口通常对字段格式要求严格，需要检查：

• 金额应使用整数形式的最小货币单位，还是小数金额；
• 小数点是否固定使用 .；
• 金额中是否包含千位分隔符；
• 币种代码是否为网关接受的值；
• 姓名、地址或订单号中是否含有网关无法处理的字符；
• 必填字段是否为空；
• 参数编码是否符合接口要求。

可以使用金额较小、字段内容简单的测试订单来排除数据问题，例如只用 ASCII 字符填写姓名和地址。不要在生产环境中反复提交真实银行卡交易。

临时增加调试记录

如果现有支付日志没有保存原始响应，可以在对应的 DirectOne 支付模块中临时记录请求结果。不同 X-Cart 版本的模块位置和日志函数并不相同。修改前要先备份文件，并确认所编辑的处理器正是当前启用的处理器。

最低限度的 PHP 调试示例如下：

error_log(
    'DirectOne HTTP status: ' . (string) $httpStatus .
    '; response: ' . (string) $response
);

如果需要记录请求参数，必须先删除敏感字段：

$debugRequest = $request;

foreach ([
    'card_number',
    'cardNumber',
    'cc_number',
    'cvv',
    'cvc',
    'security_code'
] as $sensitiveKey) {
    if (isset($debugRequest[$sensitiveKey])) {
        $debugRequest[$sensitiveKey] = '[REDACTED]';
    }
}

error_log('DirectOne request: ' . print_r($debugRequest, true));

调试完成后，应移除临时代码，并删除不再需要的敏感日志。

安全注意事项

不要在日志、工单或公开页面中发布以下内容：

• 完整银行卡号；
• CVV/CVC；
• API 密钥和商户密码；
• 完整的支付请求签名；
• 客户个人资料；
• 可重复使用的会话令牌。

即使是内部日志，也不能记录 CVV。如果排查确实需要银行卡号，最多只能保留符合业务及合规要求的掩码形式。

也不要通过关闭 TLS 证书验证来处理连接问题，例如：

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

这种做法只会掩盖证书或 CA 配置错误，同时降低支付连接的安全性。

如果仍然只有 System Error

整理好以下信息后，联系 DirectOne 或当前支付服务商：

• 交易发生的准确时间和时区；
• 使用的是测试环境还是生产环境；
• 商户号的非敏感标识；
• 订单号；
• HTTP 状态码；
• 网关返回的完整非敏感响应；
• 网关交易编号或 reference；
• X-Cart 大版本；
• PHP、cURL 和 OpenSSL 版本。

支付服务商通常可以根据时间、商户号和交易 reference 找到网关内部错误。如果 DirectOne 已停止维护当前接口，继续修改 X-Cart 配置也无法解决问题。此时需要升级支付模块、改用服务商提供的新接口，或者更换仍受支持的支付方式。

查找技术资料时，应优先使用与实际 X-Cart 大版本相符的支付网关开发文档、安装包内的对应处理器源码，以及支付服务商的接口文档。网上针对旧版 X-Cart 的帖子只能作为排查线索，因为目录结构、日志函数和 DirectOne 接口都可能已经发生变化。

备注：内容仅供参考。