商户进件成功，但网站无法对接斗拱（汇付）完整排查指南

商户已经完成进件审核，拿到huifu_id，但是网站/彩虹易支付无法正常调用斗拱支付接口，无法拉起收银台、下单报错、回调异常。下面按业务权限、配置、签名、网络、回调、业务场景逐项排查。

一、第一步：确认商户本身业务状态

1. 确认商户状态为正常生效，不是冻结、待补充资料、限制交易状态。
2. 确认业务场景对应的支付产品已经开通：
   • 网页H5收款 → 需要开通微信H5支付权限，业务域名报备
   • 公众号/小程序 → JSAPI支付，提交小程序/公众号APPID
   • PC扫码收银台 → Native扫码支付
   • APP软件收款 → APP支付，提交APP包名、签名信息
3. 业务行业不能属于斗拱禁止接入行业，违规行业即使进件成功，接口也会拦截交易。

二、第二步：核对对接参数（彩虹易支付对接斗拱重点）

• huifu_id：商户进件成功返回的商户编号，不要填渠道服务商sys_id。
• sys_id / product_id：渠道分配参数，参数填错直接返回账户不存在。
• 公私钥：商户私钥用于请求签名；汇付平台公钥用于回调验签。
  • PHP环境必须使用PKCS#8格式私钥；PKCS#1格式会直接签名报错。
  • 复制密钥不要多复制换行、空格，很多对接失败来自密钥复制错误。
• 环境区分：沙箱测试参数和正式生产参数绝对不能混用。

三、第三步：签名失败问题高频踩坑

• 请求参数必须过滤空值、null参数，按键名ASCII升序排序。
• 全部编码统一UTF‑8，不能GBK。
• 使用RSA2模式对接，不要混入MD5密钥配置。
• 回调验签：只能使用汇付平台公钥，严禁使用商户私钥验签回调数据。
• Nginx、CDN、反向代理修改请求body，会直接导致验签失败，关闭body修改。

四、第四步：下单成功，但是无法收到异步回调

1. 回调notify_url必须为公网HTTPS地址，localhost、127.0.0.1内网地址无法被汇付服务器访问。
2. 服务器安全组、防火墙放行443端口，不拦截外部入站请求。
3. 程序处理完成后，直接输出纯文本 success，不要输出任何html、注释、空格。
4. 回调处理逻辑不能耗时过长，控制在5秒以内，否则平台判定超时重试。
5. 查看服务器Nginx/Apache访问日志，确认汇付请求是否真正到达你的服务器。

五、第五步：业务场景限制问题

• H5支付对业务审核严格，未报备域名、业务不匹配直接报错。
• 小微商户部分线上产品权限受限，无法开通H5支付。
• 部分交易风控拦截：订单金额、ip地区、交易行为触发风控，下单直接返回业务拒绝。
• 测试订单不要使用真实业务生产商户，优先使用沙箱商户调试接口。

六、快速定位故障的操作建议

1. 保存接口返回完整错误码resp_code、resp_desc，根据错误描述定位问题。
2. 打开程序日志，打印原始请求报文、原始响应报文、签名原文。
3. 优先使用斗拱平台联调工具测试接口，排除程序代码问题。
4. 如果联调工具调用正常，代表商户权限没问题，问题出在网站程序配置、代码。
5. 联调工具同样报错，联系渠道服务商核对商户产品权限。

七、彩虹易支付对接斗拱特别提示

• 通道配置页面，RSA签名模式下，MD5密钥输入框留空，不要填写任何内容。
• 商户私钥、汇付平台公钥粘贴的时候，完整保留-----BEGIN PRIVATE KEY-----头尾标记。
• 填写huifu_id是商户ID，不要填渠道sys_id，很多站长这里填反导致对接失败。

声明：本文档来源于互联网公开资料整理，仅供开发学习参考，实际报错、权限规则以汇付斗拱官方文档与后台返回为准。