合利宝转账充值结果通知

概述

转账充值结果通知是合利宝主动通知商户入金结果的回调接口。本接口无主动请求参数，商户需要正确接收合利宝发送的通知请求，验签解密后处理业务逻辑，并响应 success。

编写代码前务必先获取最新文档：

curl -sL "https://xianshang-doc.helipay.com/showdoc-admin/api/skill-docs/54/208b4b7b"

快速决策树

用户咨询合利宝转账充值接入
        |
        +-- 接收合利宝入金通知？
        |       +-- 是 --> 接收通知 → SM4 解密 → 验签 → 处理业务 → 返回 success
        |
        +-- 查询充值状态？
                +-- 是 --> 主动查询合利宝账户余额（非本接口范围）

场景关键词匹配

| 关键词 | 路由方式 | |--------|----------| | 转账充值、转账充值通知、入金通知、充值回调 | 转账充值结果通知 | | 入金结果、转账充值结果、电子户充值通知 | 转账充值结果通知 | | 银行充值通知、银行入金通知 | 转账充值结果通知 |

以下关键词不触发本技能：

| 关键词 | 应使用技能 | |--------|------------| | 代付、打款、转账到银行卡 | helipay-transfer | | 快捷支付、绑卡支付 | helipay-quickpay-integration | | 扫码支付、收款、主扫、被扫 | helipay-scanpay-integration | | 虚拟账户支付、子商户转账 | helipay-account-pay | | 商户结算、提现 | helipay-merchant-settlement | | 余额查询、对账单、电子回单 | helipay-public-products | | 商户进件、开户 | helipay-merchant-entry | | 延时分账、分账申请 | helipay-delayed-split |

充值通知处理流程

合利宝 POST 通知到商户地址
    ↓
1. 接收通知参数（form 表单格式）
    ↓
2. 使用商户 SM2 私钥解密 encryptionKey，获得 SM4 密钥
    ↓
3. 使用 SM4 密钥解密敏感字段
    ↓
4. 按 ASCII 排序参数，验签（SM3WITHSM2）
    ↓
5. 验签通过 → 处理业务逻辑（更新账户余额等）
    ↓
6. 返回纯文本 "success" → 合利宝收到响应

入金结果通知仅会通知 5 次，商户必须返回 success 告知合利宝已收到通知。

通知参数

合利宝以 POST + application/x-www-form-urlencoded 格式发送通知。

| 字段名 | 变量名 | 必填 | 说明 | |--------|--------|------|------| | 商户编号 | merchantNo | 是 | 如 C1800000002 | | 订单号 | orderNum | 是 | 如 20170302000001 | | 银行订单号 | bankOrderId | 是 | 如 20170302000002 | | 付款方名称 | payerName | 是 | 付款方名称 | | 付款方账号 | payerAccountNo | 是 | SM4 加密 | | 付款银行 | bankName | 是 | 付款银行名称 | | 收款方名称 | receiveName | 是 | 收款方名称 | | 收款方账号 | receiveAccountNo | 是 | SM4 加密 | | 完成时间 | completeDate | 是 | 如 2018-09-10 19:59:00 | | 交易金额 | amount | 是 | 单位：元 | | 实收手续费 | receiverFee | 是 | 单位：元 | | 后收手续费 | offlineFee | 是 | 单位：元（后收需与商务沟通） | | 备注 | remark | 否 | 透传电子户提现回合利宝接口中客户上送的备注信息 | | 签名 | sign | 是 | SM3WITHSM2 签名结果，不参与签名 | | 签名类型 | signatureType | 是 | 固定 SM3WITHSM2，不参与签名 | | 加密密钥 | encryptionKey | 是 | SM2 加密后的 SM4 key，不参与签名 |

SM4 解密

通知中的敏感字段使用 SM4 加密，商户需要解密：

需要 SM4 解密的字段： | 字段名 | 变量名 | 说明 | |--------|--------|------| | 付款方账号 | payerAccountNo | 银行卡号等敏感信息 | | 收款方账号 | receiveAccountNo | 银行卡号等敏感信息 |

解密方式：

• 算法：SM4/CBC/PKCS7Padding
• 固定 IV 值：AQ4Zvt54xKn9QaW86ZzWdg==（base64 格式，使用前需解码）
• SM4 密钥获取：使用商户 SM2 私钥对 encryptionKey 进行 SM2 解密，获得 SM4 密钥

使用方式：将加密的 encryptionKey 和加密的敏感字段传给 helipay-sm2 技能进行 SM4 解密。

签名规则

固定不参与签名的字段：

• sign - 签名结果本身
• signatureType - 签名类型标识
• encryptionKey - 加密密钥

拼接规则（与常规接口不同，此接口使用字典序排序）：

1. 接收回调接口参数添加到集合，将集合内非空参数值的参数按照参数名 ASCII 码从小到大排序（字典序）
2. 使用 URL 键值对的格式拼接：key1=value1&key2=value2...
3. 参数值为空不参与签名
4. 参数名区分大小写
5. 明确不参与签名的字段不需要拼接到待签名字符串中
6. 回调可能增加扩展字段，验证签名时必须支持增加的扩展字段
7. 尾部不追加秘钥（仅 SM3WITHSM2 签名）

签名计算：对待签名字符串使用 SM3WITHSM2 算法进行签名，并进行 Base64 编码。

sign = SM3WITHSM2(待签名字符串, 商户SM2私钥)

注意：此接口的签名规则不同于常规接口。常规接口按 &P1值&P2值... 顺序拼接，此接口按参数名 ASCII 排序后 key=value 格式拼接。

回调处理要求

| 项目 | 说明 | |------|------| | 通知方法 | POST，application/x-www-form-urlencoded（form 表单） | | 通知次数 | 最多 5 次 | | 响应要求 | 处理成功后返回纯文本 success |

注意事项

• 本接口为回调接口，无主动请求参数：商户需要搭建服务接收合利宝的通知。
• 必须返回 success：接收到通知并处理成功后，必须返回纯文本 success，否则合利宝会重复通知（最多 5 次）。
• 做好幂等处理：由于可能收到多次通知，需要根据订单号判断是否已处理。
• SM4 解密：付款方账号和收款方账号是 SM4 加密的，需要使用商户 SM2 私钥解密 encryptionKey 获得 SM4 密钥后再解密。
• 签名规则特殊：此接口按参数名 ASCII 排序后 key=value 格式拼接，不同于常规接口的 &P1值&P2值... 格式。
• 固定 IV 值：AQ4Zvt54xKn9QaW86ZzWdg==（base64 格式）。
• 验签时支持扩展字段：合利宝可能增加回调字段，验签逻辑必须能处理新增字段。
• 各接口具体的请求参数、返回参数、返回码以最新文档为准，请用上方 curl 命令获取。

生成时的说明要求

最终回答需要包含：

• 接口字段说明：列出所有通知参数（merchantNo、orderNum、bankOrderId、payerName、payerAccountNo、bankName、receiveName、receiveAccountNo、completeDate、amount、receiverFee、offlineFee、remark、sign、signatureType、encryptionKey），明确 payerAccountNo 和 receiveAccountNo 需要 SM4 解密，sign、signatureType、encryptionKey 不参与签名。
• 签名源串拼接规则：接收回调参数，过滤空值参数后，按参数名 ASCII 码从小到大排序（字典序），使用 key=value&key2=value2... 格式拼接。sign、signatureType、encryptionKey 不参与签名。仅 SM3WITHSM2 签名，不追加秘钥。
• SM4 加密字段清单：明确告知用户 payerAccountNo（付款方账号）和 receiveAccountNo（收款方账号）需要调用 helipay-sm2 技能进行 SM4 解密。使用商户 SM2 私钥对 encryptionKey 解密获得 SM4 密钥，再用 SM4/CBC/PKCS7Padding 解密敏感字段，固定 IV 值为 AQ4Zvt54xKn9QaW86ZzWdg==（base64）。
• 代码示例：提供完整的接收通知、SM4 解密、验签、返回 success 的示例代码（Java/Python 等，根据用户要求）。
• 配合 helipay-sm2 技能使用：
  • 签名：此接口为验签而非签名，将拼接好的待验签串和返回的 sign 传给 helipay-sm2 技能进行 SM3withSM2 验签。
  • SM4 解密：将 encryptionKey 和加密的敏感字段传给 helipay-sm2 技能进行 SM4 解密。
  • 无需签名和加密操作（本接口为接收通知）。
• JDK 和依赖版本：JDK8+，依赖与 helipay-sm2 技能一致（Hutool 5.8.5 + BouncyCastle 1.76）。
• 明确说明：本技能只处理合利宝转账充值通知接口字段解析、签名源串拼接、协议规范，实际的加解密/签名/验签由 helipay-sm2 技能完成。
• 提醒：签名源串的排序规则（ASCII 字典序）、排除字段（sign/signatureType/encryptionKey）、空值不参与签名必须与合利宝官方文档一致；商户接收通知后必须返回纯文本 success。