本文旨在解决realex/global payments集成中常见的“sha1hash incorrect”错误，特别是针对`payer-new`请求类型。核心问题在于为`payer-new`请求计算sha1哈希时，误将支付金额和货币信息包含在哈希字符串中。教程将详细解释realex哈希生成机制，指出错误原因，并提供正确的哈希字符串构建方法，以确保api请求的安全性与准确性。
Realex/Global Payments SHA1哈希机制概述
Realex（现Global Payments）的API集成依赖于SHA1哈希算法来验证请求数据的完整性和真实性。每个发送到Realex的请求都必须包含一个正确的SHA1哈希值。这个哈希值通常由一系列关键数据字段和一个预共享密钥（secret）通过特定顺序拼接后计算得出。如果哈希计算不正确，Realex服务器会返回错误代码505，并附带消息“sha1hash incorrect - check your code and the Developers Documentation”。
哈希计算通常遵循两步过程：
- 第一步哈希: 将一系列特定字段按规定顺序拼接成一个字符串，然后计算其SHA1值。
- 第二步哈希: 将第一步计算出的SHA1值与您的预共享密钥拼接，再计算一次SHA1值。
最终的SHA1哈希值将包含在请求的XML或POST数据中。
“sha1hash incorrect”错误：payer-new请求的常见陷阱
在集成Realex支付解决方案时，开发者可能会遇到在提交payer-new请求时收到“sha1hash incorrect”的错误。payer-new请求的目的是在Realex系统中注册一个新的付款人（payer）信息，而不是进行实际的支付交易。
问题描述
当尝试向Realex发送包含客户姓名、客户编号、客户参考等信息的payer-new请求时，可能会收到如下错误响应：
OUR MERCHANT ID IS INSERTED HERE website scsi45880 505 sha1hash incorrect - check your code and the Developers Documentation
这表明计算出的SHA1哈希与Realex期望的不符。
错误原因分析
根据Realex的文档，不同类型的请求需要包含不同的字段来计算SHA1哈希。对于一个payer-new请求，其核心目的是注册付款人信息，因此，与支付金额和货币相关的字段（如amount和currency）不应被包含在哈希计算的原始字符串中。
在提供的代码示例中，用于计算payer-new请求的哈希（payersha1hash）的临时变量payer_temp_var被错误地构建：
// 错误的哈希字符串构建 $payer_temp_var = "$timestamp.$merchantid.$rlx_orderid.$pay_amount.$currency.$payer_ref"; $payersha1hash = sha1($payer_temp_var); $payertmp = "$payersha1hash.$payer_secret"; $payersha1hash = sha1($payertmp);
这里，$pay_amount和$currency被不当地包含在了payer_temp_var中。由于payer-new请求本身不涉及具体的交易金额，Realex在验证此请求的哈希时，不会期望这些字段出现在哈希计算字符串中。
解决方案：正确构建payer-new请求的哈希字符串
解决此问题的关键是移除payer_temp_var中不属于payer-new请求哈希计算的字段。根据Realex的API规范，对于payer-new请求，用于生成第一步哈希的字符串应只包含时间戳、商户ID、订单ID和付款人参考（payer reference）。
修正后的哈希字符串构建
将payer_temp_var的构建方式修改为：
// 正确的哈希字符串构建 $payer_temp_var = "$timestamp.$merchantid.$rlx_orderid.$payer_ref"; $payersha1hash = sha1($payer_temp_var); $payertmp = "$payersha1hash.$payer_secret"; $payersha1hash = sha1($payertmp);
通过移除$pay_amount和$currency，现在payer_temp_var只包含payer-new请求所需的核心字段。
示例代码（关键部分）
以下是PHP中正确计算payer-new请求SHA1哈希的关键代码片段：
$merchantid
$account
$rlx_orderid
$payersha1hash
";
// ... (使用 cURL 发送请求的代码) ...
// --- 针对 Auth (支付授权) 请求的 SHA1 哈希计算 (作为对比) ---
// 注意：这里需要包含 $pay_amount, $currency 和 $cardNumber
$amount = $_POST['amount'];
$pay_amount = $amount * 100; // 金额通常以最小货币单位表示 (例如：欧元分)
$currency = "EUR";
$cardNumber = $_POST['cardnnumber']; // 实际卡号，用于哈希，但通常不直接发送到API
$auth_temp_var = "$timestamp.$merchantid.$rlx_orderid.$pay_amount.$currency.$cardNumber";
$sha1hash_auth = sha1($auth_temp_var);
$authtmp = "$sha1hash_auth.$secret"; // 使用主密钥
$sha1hash_auth = sha1($authtmp);
// 构建 Auth XML 请求
$field_string = "
$merchantid
$account
MOTO
$rlx_orderid
$pay_amount
$cardNumber
...
...
...
...
$sha1hash_auth
";
// ... (使用 cURL 发送请求的代码) ...
?>注意事项与最佳实践
- 查阅官方文档: Realex/Global Payments的API文档是生成正确哈希的最终权威来源。务必针对您正在使用的具体API版本和请求类型，仔细查阅其哈希计算要求。
- 区分请求类型: 不同API请求（如auth、payer-new、settle等）的哈希字符串组成可能完全不同。不要混淆或复用哈希计算逻辑。
- 密钥管理: Realex可能为不同的操作（如主交易、付款人管理）提供不同的共享密钥。确保为每个哈希计算使用正确的密钥。密钥是敏感信息，应妥善保管，切勿硬编码在前端代码中或通过不安全的方式传输。
- 数据类型和格式: 确保所有参与哈希计算的字段都符合Realex要求的格式（例如，金额通常是整数，表示最小货币单位）。
- 调试技巧: 如果遇到哈希错误，可以使用error_log或类似的调试工具输出payer_temp_var和payertmp在计算前的完整字符串，以及最终生成的哈希值。然后对照Realex文档，手动验证这些字符串和哈希是否正确。
- 错误日志: 详细记录Realex的响应，包括result代码和message，这对于诊断问题至关重要。
总结
Realex/Global Payments集成中的“sha1hash incorrect”错误通常源于对哈希计算字符串中包含字段的误解。对于payer-new这类非交易性请求，关键在于只包含与付款人注册直接相关的字段（时间戳、商户ID、订单ID、付款人参考），而排除支付金额和货币等交易性字段。遵循Realex的API文档，并仔细核对每个请求类型的哈希计算规则，是确保集成顺利和交易安全的关键。
