如何通过 Payeer payment API 显示钱包余额？

2026-10-24支付阿杰

结论

这段调用流程没有明显问题。最常见的原因是 PHP 短标签 <? 未启用，代码实际上并未执行。先改用标准的 <?php，然后确认 cpayeer.php 路径无误、API 凭据有效，并分别查看认证错误和 getBalance() 的返回结果。

示例中的账号和 API 凭据已经出现在公开内容中。请立即前往 Payeer 后台撤销或更换相关密钥，不要继续使用原有凭据。

建议修改后的代码

<?php

require_once __DIR__ . '/cpayeer.php';

$accountNumber = 'PXXXXXXXXXX';
$apiId = 'YOUR_API_ID';
$apiKey = 'YOUR_API_KEY';

$payeer = new CPayeer($accountNumber, $apiId, $apiKey);

if (!$payeer->isAuth()) {
    echo '<pre>';
    print_r($payeer->getErrors());
    echo '</pre>';
    exit;
}

$balance = $payeer->getBalance();

if ($balance === false || $balance === null) {
    echo '<pre>';
    print_r($payeer->getErrors());
    echo '</pre>';
    exit;
}

echo '<pre>';
print_r($balance);
echo '</pre>';

这段代码主要做了两处调整：

将短标签改为完整的 <?php，防止服务器禁用 short_open_tag 后代码无法执行。
通过 __DIR__ . '/cpayeer.php' 加载文件，避免当前工作目录不同而导致加载失败。

按顺序排查

1. 确认 PHP 正在执行

创建一个最小测试页面：

<?php

echo 'PHP is running';

如果浏览器没有显示这段文字，或者直接显示了 PHP 源码，说明 Web 服务器尚未正确处理 PHP。这个问题与 Payeer API 无关。

2. 在开发环境中打开错误报告

页面空白通常是因为 PHP 错误被隐藏了。可以在开发或排查环境中临时加入：

<?php

error_reporting(E_ALL);
ini_set('display_errors', '1');

require_once __DIR__ . '/cpayeer.php';

如果出现 Failed opening required，说明 cpayeer.php 不在预期目录。如果提示类不存在，则要检查 SDK 文件是否完整，以及文件中是否确实定义了 CPayeer。

不要在生产环境中长期启用 display_errors，否则错误信息可能暴露服务器路径或其他敏感数据。

3. 检查 API 凭据

$accountNumber、$apiId 和 $apiKey 必须来自同一个 Payeer API 配置，不能混用：

$accountNumber = 'PXXXXXXXXXX';
$apiId = 'YOUR_API_ID';
$apiKey = 'YOUR_API_KEY';

复制凭据后，还要逐项检查：

是否包含前后空格；
API 配置是否仍处于启用状态；
密钥是否已经重置；
后台是否设置了 IP 白名单；
当前服务器的公网 IP 是否在允许范围内；
当前账户或 API 权限是否允许查询余额。

具体字段名称和权限规则可能因 Payeer 接口及 SDK 版本而异，请以账户后台和对应版本的 SDK 文档为准。

4. 不要只检查 `isAuth()`

认证成功不等于余额请求一定成功。网络异常、接口响应格式变化或权限限制都可能导致 getBalance() 失败，所以调用后仍需检查并输出错误：

$balance = $payeer->getBalance();

if ($balance === false || $balance === null) {
    print_r($payeer->getErrors());
} else {
    print_r($balance);
}

不要用 if (!$balance) 判断请求是否失败，因为某些合法的空数据结构也会被 PHP 视为假值。

5. 检查服务器能否访问接口

如果代码和凭据都没有问题，还要确认服务器能够发起 HTTPS 请求。常见原因包括：

PHP cURL 扩展未安装或未启用；
DNS 无法解析接口域名；
防火墙阻止出站 HTTPS 请求；
CA 证书过旧，导致 TLS 验证失败；
主机时间不准确；
cpayeer.php 版本过旧或已经不兼容。

可以用下面的代码检查扩展是否已经加载：

<?php

var_dump(extension_loaded('curl'));
var_dump(OPENSSL_VERSION_TEXT);

不要关闭 SSL 证书验证来绕过 TLS 错误。正确的处理方式是更新系统 CA 证书、PHP、cURL、OpenSSL 或相关服务器配置。

只显示某一种货币

getBalance() 通常返回数组，不能当作普通字符串直接输出。不同 CPayeer 实现或接口版本的返回结构可能不同，因此应先查看实际结果：

echo '<pre>';
print_r($balance);
echo '</pre>';

确认数组结构后，再读取目标币种。例如，如果实际结果中存在 balance['USD']['DOSTUPNO']，可以这样处理：

if (isset($balance['balance']['USD']['DOSTUPNO'])) {
    echo htmlspecialchars(
        (string) $balance['balance']['USD']['DOSTUPNO'],
        ENT_QUOTES,
        'UTF-8'
    );
} else {
    echo '未在 API 响应中找到 USD 可用余额';
}

这里的数组路径只是条件示例。在查看真实响应之前，不能直接认定它适用于当前 SDK。

安全注意事项

不要将 API 密钥硬编码到公开可访问的源码仓库中。更稳妥的做法是从环境变量读取：

$accountNumber = getenv('PAYEER_ACCOUNT');
$apiId = getenv('PAYEER_API_ID');
$apiKey = getenv('PAYEER_API_KEY');

生产页面也不应直接向访客输出完整的 getErrors() 或原始 API 响应。排查结束后，应将这些信息写入受保护的服务器日志，页面只返回简短的错误提示。