Realex集成SHA1哈希不匹配问题解析与修复

本文旨在解决Realex/Global Payments支付网关集成中常见的“SHA1哈希不正确”（错误代码505）问题。通过分析问题根源，我们发现该错误通常源于payer-new请求类型在计算SHA1哈希时错误地包含了金额和货币信息。教程将详细阐述正确的哈希计算方法，并提供示例代码，帮助开发者确保数据完整性与交易安全性，顺利完成Realex支付集成。

理解Realex支付网关的SHA1哈希机制

Realex（现为Global Payments的一部分）支付网关在处理交易请求时，为了确保数据的完整性和安全性，广泛采用了SHA1哈希算法。每次向Realex发送请求时，都需要根据特定的参数组合生成一个SHA1哈希值，并将其包含在请求中。Realex服务器会使用相同的逻辑重新计算哈希值，如果客户端发送的哈希值与服务器计算的不匹配，便会返回“SHA1哈希不正确”的错误（通常是错误代码505）。

Realex的哈希计算通常涉及两个步骤：

1. 数据哈希（Data Hash）：将一系列核心交易参数按照特定顺序拼接成一个字符串，然后计算其SHA1哈希值。
2. 秘密哈希（Secret Hash）：将上一步生成的数据哈希值与商户的共享秘密（Secret）拼接，再次计算SHA1哈希值。最终将这个二次哈希值发送给Realex。

这种双重哈希机制旨在防止数据在传输过程中被篡改，并验证请求的真实性。

“SHA1哈希不正确”错误（505）的常见原因

当收到以下错误响应时：

<response timestamp="20211208142721">
    <merchantid>OUR MERCHANT ID IS INSERTED HERE</merchantid>
    <account>website</account>
    <orderid>scsi45880</orderid>
    <result>505</result>
    <message>sha1hash incorrect - check your code and the Developers Documentation</message>
</response>

这明确指示了SHA1哈希计算存在问题。根据我们的经验，此问题通常发生在以下情境：

• 参数顺序错误：拼接哈希字符串时，参数的顺序与Realex文档要求不符。
• 参数缺失或多余：在特定请求类型中，包含了不应包含的参数，或遗漏了必需的参数。
• 秘密密钥不匹配：使用了错误的商户秘密密钥。
• 数据格式问题：某些参数（如金额）的格式不正确，导致拼接后的字符串与Realex预期不符。

针对payer-new请求的SHA1哈希修复

在Realex集成中，不同的请求类型（例如auth授权请求、payer-new创建付款人请求）对SHA1哈希的参数要求是不同的。问题中描述的错误发生在尝试发送客户名称、客户编号等数据时，这通常与payer-new（或类似的客户信息注册）请求相关。

百度文心一格

百度推出的AI绘画作图工具

112

查看详情

通过分析发现，在处理payer-new请求时，原始代码错误地将pay_amount（支付金额）和currency（货币）包含在了SHA1哈希的计算字符串中。然而，payer-new请求的主要目的是注册付款人信息，它本身并不直接涉及具体的交易金额。因此，在生成此类型的哈希时，不应包含金额和货币参数。

错误的哈希计算（示例，应避免）:

// 错误的payer-new哈希计算示例
// $payer_temp_var = "$timestamp.$merchantid.$rlx_orderid.$pay_amount.$currency.$payer_ref";
// $payersha1hash = sha1($payer_temp_var);
// $payertmp = "$payersha1hash.$payer_secret";
// $payersha1hash = sha1($payertmp);

正确的哈希计算方法:

对于payer-new请求，SHA1哈希计算的参数应仅包括时间戳、商户ID、订单ID和付款人引用（Payer Reference）。

<?php
// ... 其他初始化代码 ...

$timestamp = strftime("%Y%m%d%H%M%S");
$merchantid = 'scs'; // 替换为您的商户ID
$account = 'website'; // 替换为您的账户名
$rlx_orderid = "scsi" . rand(10000, 99999); // 生成唯一的订单ID
$payer_secret = 'YOUR_PAYER_SECRET'; // 替换为您的Payer秘密密钥

// 生成payer_ref，这是一个唯一的付款人引用
$payer_ref = sprintf('%04x%04x-%04x-%04x-%04x-%04x%04x%04x',
        mt_rand(0, 0xffff), mt_rand(0, 0xffff),
        mt_rand(0, 0xffff),
        mt_rand(0, 0x0C2f) | 0x4000,
        mt_rand(0, 0x3fff) | 0x8000,
        mt_rand(0, 0x2Aff), mt_rand(0, 0xffD3), mt_rand(0, 0xff4B)
);

// 正确的Payer sha1hash计算：不包含 $pay_amount 和 $currency
$payer_temp_var = "$timestamp.$merchantid.$rlx_orderid.$payer_ref";
$payersha1hash = sha1($payer_temp_var); // 第一次哈希

// 将第一次哈希值与Payer秘密密钥拼接进行第二次哈希
$payertmp = "$payersha1hash.$payer_secret";
$payersha1hash = sha1($payertmp); // 最终的SHA1哈希

// ... 构造payer-new XML请求并发送 ...
$payer_stirng = "<?xml version='1.0' encoding='UTF-8'?>
    <request type='payer-new' timestamp='$timestamp'>
      <merchantid>$merchantid</merchantid>
      <account>$account</account>
      <orderid>$rlx_orderid</orderid>
      <payer ref='$payer_ref' type='Retail'>
        <!-- 其他付款人详细信息 -->
      </payer>
      <sha1hash>$payersha1hash</sha1hash>
    </request>";

// ... cURL请求发送 ...
?>

注意事项：

1. 区分请求类型：务必根据Realex文档，针对不同的请求类型（如auth、payer-new、settle等）采用不同的哈希计算参数和顺序。例如，auth（授权）请求的哈希计算通常会包含金额和货币信息，因为它是一个具体的交易请求。
2. 秘密密钥：确保您使用的payer_secret是Realex为您提供的、用于Payer操作的正确秘密密钥。Realex可能为不同类型的操作提供不同的秘密密钥。
3. 参数顺序：即使参数正确，其拼接顺序也至关重要。任何顺序的改变都会导致哈希值不匹配。
4. 错误日志：在开发和调试阶段，充分利用错误日志（如error_log）来打印拼接前的哈希字符串和最终的哈希值，以便与Realex文档进行比对。
5. 官方文档：Realex的文档虽然有时不够清晰，但仍然是最终的权威参考。在遇到问题时，应仔细核对相关请求类型的哈希生成章节。

总结

解决Realex集成中“SHA1哈希不正确”的错误，核心在于严格遵循Realex文档中对每种请求类型所规定的哈希计算规则。对于payer-new请求，关键在于不将交易金额和货币包含在哈希字符串中。通过修正这一细节，并确保其他参数的正确性和顺序，可以有效解决505错误，确保支付网关通信的顺畅和安全。在处理其他Realex请求时，也应采用同样的严谨态度，对照文档，确保哈希计算的准确无误。

以上就是Realex集成SHA1哈希不匹配问题解析与修复的详细内容，更多请关注php中文网其它相关文章！