本文详解如何使用 cryptapi 提供的公钥和 sha-256 签名机制，在 php 后端安全验证回调请求真实性，并结合日志查询完成完整的支付确认逻辑，避免伪造请求与重复处理风险。
本文详解如何使用 cryptapi 提供的公钥和 sha-256 签名机制，在 php 后端安全验证回调请求真实性，并结合日志查询完成完整的支付确认逻辑，避免伪造请求与重复处理风险。
在集成 CryptAPI 支付回调时，仅验证签名并不足以确保交易真实有效——签名验证防止中间人篡改或伪造请求，但无法确认该笔回调是否对应一笔已上链、已确认、且金额达标的实际充值。因此，一个健壮的回调处理流程应包含两个关键阶段：（1）签名合法性校验；（2）服务端主动查证交易状态。
✅ 第一阶段：严格验证 X-CA-Signature
原始代码中存在多个关键缺陷，导致 openssl_verify() 恒返回失败：
- ❌ 数据拼接错误：CryptAPI 文档明确说明，待签名原文（
data）是 原始 HTTP 请求体的原始字节流（raw body），不进行 URL 解码、不拼接 query string、不添加协议/主机名。你代码中对 GET 请求使用了https://$_SERVER[HTTP_HOST]$_SERVER[REQUEST_URI]，这完全违背规范；对 POST 请求虽用了php://input，但未考虑Content-Type: application/x-www-form-urlencoded场景下需还原为原始键值对字符串（如a=1&b=2），而非 JSON 或二进制数据。 - ❌ 公钥格式隐患：换行符
\n在 PHP 字符串中若未被正确解析（如定义在单引号内），会导致公钥加载失败。建议使用定界符（heredoc）或确保双引号+转义。 - ❌ 缺少请求方法判断与边界处理：未统一处理 GET/POST 差异，也未校验
X-CA-Signature头是否存在。
✅ 正确做法如下（适配 CryptAPI v2+ 回调）：
<?php
// 1. 获取并清理签名头（必须存在）
if (!isset($_SERVER['HTTP_X_CA_SIGNATURE'])) {
http_response_code(400);
echo "Missing X-CA-Signature header";
exit;
}
$signature = base64_decode($_SERVER['HTTP_X_CA_SIGNATURE']);
// 2. 构造待签名原文：原始请求体（PHP 7.4+ 推荐 file_get_contents('php://input', false, null, 0, 1048576) 限制 1MB）
$body = file_get_contents('php://input');
if ($body === false) {
$body = ''; // 空 body 也是合法的（如某些 GET 回调）
}
// 3. 加载公钥（推荐使用 heredoc 避免换行问题）
$pubkey = <<<EOD
-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC3FT0Ym8b3myVxhQW7ESuuu6lo
dGAsUJs4fq+Ey//jm27jQ7HHHDmP1YJO7XE7Jf/0DTEJgcw4EZhJFVwsk6d3+4fy
Bsn0tKeyGMiaE6cVkX0cy6Y85o8zgc/CwZKc0uw6d5siAo++xl2zl+RGMXCELQVE
ox7pp208zTvown577wIDAQAB
-----END PUBLIC KEY-----
EOD;
// 4. 验证签名（SHA256 + RSA-PKCS1-v1_5）
$result = openssl_verify($body, $signature, $pubkey, OPENSSL_ALGO_SHA256);
if ($result !== 1) {
error_log("Callback signature verification failed. Body length: " . strlen($body));
http_response_code(401);
echo "Invalid signature";
exit;
}
// 签名验证通过 —— 请求来源可信⚠️ 注意事项：
立即学习“PHP免费学习笔记（深入）”；
- 不要对
$body做urldecode()、json_decode()或任何修改，必须保持原始字节一致；- 若使用 Nginx + PHP-FPM，确保
client_max_body_size和php.ini中post_max_size/upload_max_filesize足够容纳可能的大回调体；- 公钥务必与 CryptAPI 控制台中「Webhook Public Key」完全一致（含首尾横线与换行）。
✅ 第二阶段：主动查询交易日志（推荐方案）
即使签名有效，也不能直接信任 $_GET['amount'] —— 攻击者可构造恶意回调。必须通过 CryptAPI 日志 API 主动查询该订单的实际入账状态：
// 示例：从回调中提取唯一标识（如 order_id）与币种（logticker）
if (!isset($_GET['order_id']) || !isset($_GET['logticker'])) {
http_response_code(400);
echo "Missing required parameters";
exit;
}
$order_id = (int)$_GET['order_id'];
$logticker = $_GET['logticker']; // e.g., 'btc', 'trc20_usdt'
// 构建回调地址（注意：必须与 CryptAPI 后台配置的 callback URL 完全一致，包括 query 参数顺序！）
$callback_url = 'https://' . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'];
// 对 callback_url 进行严格 urlencode（CryptAPI 日志接口要求精确匹配）
$query = http_build_query(['callback' => rawurlencode($callback_url)]);
$api_url = "https://api.cryptapi.io/{$logticker}/logs/?{$query}";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $api_url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 15,
CURLOPT_USERAGENT => 'CryptAPI-Validator/1.0',
]);
$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($http_code !== 200 || !$response) {
error_log("Failed to fetch logs from CryptAPI: HTTP {$http_code}");
http_response_code(500);
echo "Service unavailable";
exit;
}
$data = json_decode($response, true);
if (json_last_error() !== JSON_ERROR_NONE || !isset($data['status']) || $data['status'] !== 'success') {
error_log("Invalid CryptAPI log response: " . print_r($data, true));
http_response_code(500);
echo "Invalid API response";
exit;
}
$total_confirmed = 0.0;
$confirmed_txs = [];
foreach ($data['callbacks'] as $cb) {
// 只处理已确认（pending == 0）且成功转发（result === 'sent'）的记录
if ((int)$cb['pending'] === 0 && $cb['result'] === 'sent') {
$value_coin = (float)$cb['value_coin'];
$total_confirmed += $value_coin;
$confirmed_txs[] = [
'txid_in' => $cb['txid_in'] ?? '',
'value_coin' => $value_coin,
'uuid' => $cb['uuid'] ?? '',
'last_update' => $cb['last_update'] ?? ''
];
}
}
// 核心业务逻辑：判断是否达到预期金额（支持精度容错，如 BTC 使用 8 位小数）
$expected_amount = (float)$_GET['amount'];
if ($total_confirmed >= $expected_amount * 0.999) { // 允许 0.1% 浮动（防舍入误差）
// ✅ 执行发货、更新订单状态、发送通知等业务操作
updateOrderStatus($order_id, 'paid', $confirmed_txs, $total_confirmed);
echo "*ok*"; // CryptAPI 要求返回 *ok* 表示成功
} else {
error_log("Insufficient confirmed amount for order {$order_id}: got {$total_confirmed}, need {$expected_amount}");
echo "Amount not met";
}? 最佳实践总结
- 永远不要信任客户端传来的金额或状态字段，一切以链上确认为准；
- 签名验证是第一道门禁，日志查询是第二道审计，二者缺一不可；
-
使用
rawurlencode()而非urlencode()处理 callback 参数，确保与 CryptAPI 存储的 URL 100% 一致（尤其@→%40）； -
为每个订单生成唯一
order_id并作为回调参数传递，便于幂等处理与对账； - 记录完整日志（签名验证结果、API 响应、最终判定），便于故障排查与合规审计；
- 设置合理的 cURL 超时（建议 ≤15s）并捕获网络异常，避免阻塞 Web 服务器。
通过以上双重校验机制，你的 PHP 应用即可安全、可靠地接入 CryptAPI，杜绝假回调与金额欺诈风险。
