接入前置条件

开始接入前，请核对以下4项条件，缺一不可，否则后续实名认证或接口调用将直接中断。

  • 企业营业执照（三证合一）：彩虹官网平台仅向持有营业执照的企业或个体工商户开放服务商权限。个人身份无法完成服务商等级认证。需确保执照在有效期内，且经营范围与技术服务、电子商务相关，否则可能导致认证被驳回。
  • 已备案域名：你需要提供一个已完成ICP备案的域名，用于绑定商户后台和支付回调地址。未备案域名无法通过平台网址审核，回调请求会被防火墙屏蔽。备案主体需与营业执照一致。
  • 对公银行账户：服务商分润提现仅支持对公账户打款。账户名称必须与营业执照上的企业名称完全一致，不支持个人银行卡或第三方支付账户作为提现卡。
  • HTTPS证书：平台强制要求回调通知地址使用HTTPS协议。请提前在服务器部署有效SSL证书，证书链需完整。如使用自签名证书，回调请求将因证书不可信被平台拒绝。证书过期后的表现可参考 网站HTTPS证书过期致支付中断的复盘。

步骤一：注册平台账号并提交服务商认证

核心操作是开通服务商权限，而非普通商户账号。

在彩虹官网开放平台首页点击“加入我们”，选择“服务商”身份注册。填写企业信息时，组织名称与营业执照保持逐字一致，包括括号全角半角的匹配。上传的执照图片需四角完整露出，文件大小不超过2MB，格式为JPG或PNG。 提交后系统进入人工审核，审核时限通常为1至3个工作日。审核期间不要重复提交，否则会重置排队位置。 建议在工作日10:00至16:00提交。非工作时间提交的单据，审核流程启动会有延迟。如果超过3个工作日仍无反馈，直接在平台内“工单系统”提交催审，注明注册手机号和组织全称，响应速度比邮件快。

步骤二：创建应用并获取接口凭证

认证通过后，需创建应用以获取接口调用的身份凭证。

进入服务商控制台，选择“应用管理”，点击“创建应用”。应用名称建议填正式业务名称，如“XX商城支付网关”，便于后期区分多应用场景。 创建完成后获取三个核心参数：
  • Platform ID（平台ID）：服务商唯一标识，用于所有API请求头。
  • APP ID（应用ID）：标识具体应用，签名计算时会用到。
  • 支付密钥（KEY）：签名密钥，直接决定请求合法性。请复制后保存在服务器环境变量或加密配置文件中，不要硬编码在前端代码里，更不要提交到公共代码仓库。
密钥泄露的补救成本极高。彩虹平台没有密钥线上重置功能，只能线下联系平台客服，提交工单并邮寄盖章的变更申请函才能更换。务必一次性保管好。

步骤三：实现接口鉴权签名算法

签名生成是所有接口调用的必选项，签名错误是接入失败的主因。

彩虹开放平台采用参数名ASCII码升序排序后拼接，尾部加上支付密钥，整体进行MD5计算生成签名。参数排序时必须排除sign本身和空值参数。参数值与值之间无分隔符，仅靠参数名和参数值紧密拼接。 以下伪代码示意签名生成逻辑，可直接移植： 
kvs = sort_by_key(params)
str = ""
for k,v in kvs: str += k + v
str += key
sign = md5(str)
拼接过程极易实战经验：有的语言在提取参数时会把布尔值true转为"1"，导致拼接串不一致。建议所有参数统一转为字符串后排序。遇到签名校验失败，第一反应应该是打印签名原串，而不是怀疑算法错误。详细排错方法可参考 彩虹官方接口对接故障：签名顺序引发的排错实战。

步骤四：配置支付回调与订单查单

回调配置直接关系到订单状态能否同步更新。

在应用设置的“回调地址”栏填入完整的HTTPS URL，例如 https://your-domain.com/notify/caihong。此地址必须满足：
  • POST方法接收JSON格式数据
  • 返回纯文本字符串“success”（全部小写，不含其他字符）
  • 响应时间在5秒内完成业务逻辑处理并返回。超出5秒平台判定通知失败，会按间隔策略重试，最长重试6次。
收到回调后要执行两个动作：首先验证签名，确认数据源合法；其次根据order_status字段更新本地订单状态。订单状态以回调最终通知为准，不要依赖前端的同步返回，网络波动可能导致前端返回成功但后端未到账。 查单接口作为补偿机制，每分钟调用一次未支付订单，间隔建议不低于30秒，避免触发频率限制。深夜时段建议拉长间隔到5分钟。

验证接入是否成功

按以下3个检查点逐项验证，确保全链路跑通。

沙箱环境调试验证：使用平台提供的沙箱API地址和测试密钥，调用统一下单接口，传入虚假金额1分钱。若沙箱支付页面能拉起收银台并显示支付二维码，说明签名和请求参数正确。 日志验签验证：在服务器日志中打印每次回调的原始POST体以及本地计算的签名值。用沙箱回调URL主动触发一次模拟回调，对比日志中两处签名是否完全一致。允许字符集差异，但内容不允许有一字节偏差。 真款验证：将测试金额设为0.01元，用真实扫码支付完成一笔订单。观察商户后台订单状态是否在30秒内从“未支付”变为“支付成功”，同时检查收款账户是否确实入账0.01元。完成这一步，说明整套接入流程已验证贯通。

常见排错：签名不匹配与回调收不到

多数排错可归结为签名校验和网络可达性问题。

如果接口返回“签名校验不通过”：首先排查参数排序是否正确，必须按ASCII升序，不是字典序。注意空参数不要参与签名拼接。其次排查参数值原始性，URL编码、前后空格、emoji字符都会使拼接值发生变化。最后检查MD5算法，确保输出是小写32位十六进制字符串。 如果回调一直收不到：先查HTTPS证书是否被信任，浏览器访问回调URL是否出现安全警告。再查服务器是否配置WAF或地域限制，彩虹回调IP位于境内，如果你关闭了境内IP访问，会被直接拦截。另外需要确认回调地址的DNS解析在全球范围可用，部分自建DNS服务器在平台侧无法解析时也会导致通知中断。