彩虹易支付系统 API 开发文档

通信协议：所有接口采用 HTTPS 协议传输，确保数据安全；
编码格式：请求与响应数据均为 UTF-8 编码；
数据格式：请求参数支持 application/x-www-form-urlencoded 或 application/json，响应格式统一为 JSON；
签名机制：所有接口需通过签名验证（除登录接口），签名算法见「签名规则」章节；
接口域名：
- 正式环境：https://api.rainbowpay.com
- 沙箱测试环境：https://sandbox.rainbowpay.com（测试环境无真实资金流转，支持模拟各类交易场景）；
超时设置：建议设置请求超时时间为 30 秒，避免网络波动导致业务异常；
频率限制：单商户 API 调用频率默认限制为 100 次 / 分钟，如需提升阈值可联系客户经理申请。

前置准备

1. 账户开通与资质认证

登录彩虹易支付商户后台（https://www.wqkami.com），完成账号注册与实名认证；
申请开通 API 接入权限，审核通过后获取 merchant_no（商户号）与 api_key（API 密钥）；
如需使用插件功能（如跨境支付、智能分账），需先在商户后台开通对应插件并完成配置。

2. 签名规则

所有 API 请求需携带签名参数 sign，用于验证请求合法性，签名生成步骤如下：

收集所有非空请求参数（不包含 sign 本身），按参数名 ASCII 字典序 排序；
将排序后的参数以 key=value 形式拼接，末尾拼接 &api_key=商户api_key；
对拼接后的字符串进行 MD5 加密（32 位大写），结果即为 sign 值。

签名示例

假设商户号 merchant_no=20250001，API 密钥 api_key=abc123456，请求参数如下：

参数名	参数值
merchant_no	20250001
out_trade_no	20251124001
total_amount	100.00
body	测试支付

步骤 1：按 ASCII 排序参数：body=测试支付&merchant_no=20250001&out_trade_no=20251124001&total_amount=100.00

步骤 2：拼接 API 密钥：body=测试支付&merchant_no=20250001&out_trade_no=20251124001&total_amount=100.00&api_key=abc123456

步骤 3：MD5 加密结果：E88889999000011112222333344445555（示例值）

3. 通用响应格式

所有 API 响应均返回统一 JSON 格式，包含状态码、提示信息及业务数据：

json

{
  "code": 200,          // 状态码：200=成功，其他为失败
  "msg": "操作成功",     // 提示信息
  "data": {},           // 业务数据（成功时返回，失败时可能为null）
  "sign": "xxx"         // 响应签名（用于验证响应合法性，生成规则同请求签名）
}

状态码说明

状态码	说明	处理建议
200	操作成功	正常处理业务数据
400	参数错误	检查请求参数是否完整、格式是否正确
401	签名错误	核对签名生成步骤、api_key 是否正确
403	权限不足	检查 API 接入权限、插件开通状态
404	接口不存在	核对接口路径是否正确
500	系统异常	记录日志，联系技术支持
600	业务失败	查看 msg 字段提示（如订单不存在、余额不足）

核心 API 接口

一、支付相关接口

1. 统一支付接口（支持多支付方式）

接口描述：发起支付请求，支持微信支付、支付宝、银联云闪付、数字人民币等主流支付方式，自动返回对应支付链接 / 参数；
接口地址：/api/v4/pay/unified
请求方式：POST
请求参数：

参数名	类型	是否必填	描述	示例值
merchant_no	String	是	商户号	20250001
out_trade_no	String	是	商户订单号（唯一，长度≤32 位）	20251124001
total_amount	Decimal	是	支付金额（单位：元，保留 2 位小数）	100.00
body	String	是	订单描述（长度≤128 位）	测试支付
pay_type	String	是	支付方式：wechat = 微信支付，alipay = 支付宝，unionpay = 银联，dc = 数字人民币，cross = 跨境支付	wechat
notify_url	String	是	支付结果回调地址（需公网可访问）	https://www.merchant.com/notify
return_url	String	否	支付成功后跳转地址（H5 / 网站场景）	https://www.merchant.com/success
client_ip	String	否	客户端 IP 地址	127.0.0.1
extra	String	否	额外参数（JSON 格式，如跨境支付的币种、免签支付的回调参数）	{“currency”:”CNY”}
sign	String	是	签名值	E88889999000011112222333344445555

响应数据（code=200）：

json

{
  "code": 200,
  "msg": "支付请求成功",
  "data": {
    "trade_no": "R2025112400001",  // 彩虹易支付订单号
    "pay_type": "wechat",          // 支付方式
    "pay_info": {                  // 支付参数（不同支付方式格式不同）
      "type": "qrcode",            // 支付类型：qrcode=二维码，url=跳转链接，params=APP参数
      "value": "https://pay.rainbowpay.com/qrcode/xxx"  // 支付链接/二维码地址
    },
    "expire_time": 3600            // 订单有效期（秒，默认3600秒）
  },
  "sign": "xxx"
}

2. 订单查询接口

接口描述：查询订单支付状态、支付金额、支付时间等信息；
接口地址：/api/v4/pay/query
请求方式：POST
请求参数：

参数名	类型	是否必填	描述	示例值
merchant_no	String	是	商户号	20250001
out_trade_no	String	二选一	商户订单号	20251124001
trade_no	String	二选一	彩虹易支付订单号	R2025112400001
sign	String	是	签名值	E88889999000011112222333344445555

响应数据（code=200）：

json

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "merchant_no": "20250001",
    "out_trade_no": "20251124001",
    "trade_no": "R2025112400001",
    "total_amount": 100.00,
    "pay_amount": 100.00,          // 实际支付金额
    "pay_type": "wechat",
    "status": "SUCCESS",           // 订单状态：INIT=初始化，PROCESSING=处理中，SUCCESS=支付成功，FAILED=支付失败，CLOSED=已关闭
    "pay_time": "2025-11-24 10:00:00",  // 支付时间（SUCCESS状态时返回）
    "notify_status": "UNNOTIFIED", // 回调状态：UNNOTIFIED=未回调，SUCCESS=回调成功，FAILED=回调失败
    "body": "测试支付"
  },
  "sign": "xxx"
}

3. 退款接口

接口描述：发起订单退款，支持全额退款或部分退款，退款资金原路返回用户支付账户；
接口地址：/api/v4/pay/refund
请求方式：POST
请求参数：

参数名	类型	是否必填	描述	示例值
merchant_no	String	是	商户号	20250001
out_refund_no	String	是	商户退款单号（唯一，长度≤32 位）	REF20251124001
out_trade_no	String	二选一	商户订单号	20251124001
trade_no	String	二选一	彩虹易支付订单号	R2025112400001
refund_amount	Decimal	是	退款金额（单位：元，≤订单支付金额）	50.00
refund_desc	String	否	退款说明	商品质量问题
sign	String	是	签名值	E88889999000011112222333344445555

响应数据（code=200）：

json

{
  "code": 200,
  "msg": "退款请求成功",
  "data": {
    "refund_no": "RF2025112400001",  // 彩虹易支付退款单号
    "out_refund_no": "REF20251124001",
    "trade_no": "R2025112400001",
    "refund_amount": 50.00,
    "status": "PROCESSING",          // 退款状态：PROCESSING=处理中，SUCCESS=退款成功，FAILED=退款失败
    "refund_time": "2025-11-24 10:30:00",
    "notify_url": "https://www.merchant.com/refund_notify"  // 退款结果回调地址
  },
  "sign": "xxx"
}

二、回调通知接口

1. 支付结果回调通知

接口描述：用户支付成功后，彩虹易支付系统会向商户配置的 notify_url 发送异步回调通知，商户需验证签名并返回成功响应；
请求方式：POST
回调参数（商户需解析并验证）：

参数名	类型	描述	示例值
merchant_no	String	商户号	20250001
out_trade_no	String	商户订单号	20251124001
trade_no	String	彩虹易支付订单号	R2025112400001
total_amount	Decimal	支付金额	100.00
pay_type	String	支付方式	wechat
pay_time	String	支付时间	2025-11-24 10:00:00
sign	String	签名值	E88889999000011112222333344445555

商户响应要求：
1. 必须返回 JSON 格式数据，且仅包含 code 和 msg 字段；
2. 验证签名通过后，返回 {"code":200,"msg":"success"}，否则彩虹易支付会重复回调（重试规则：15 秒、30 秒、1 分钟、3 分钟、5 分钟、10 分钟、30 分钟、1 小时，共 8 次）。

2. 退款结果回调通知

接口描述：退款状态变更后，向商户退款时配置的 notify_url 发送回调通知；
请求参数与响应要求同「支付结果回调通知」，新增 refund_no（退款单号）、refund_amount（退款金额）、refund_status（退款状态）参数。

三、插件功能接口（示例：智能分账插件）

1. 分账订单创建接口

接口描述：仅支持已开通「智能分账插件」的商户调用，创建分账订单并指定分账规则；
接口地址：/api/v4/plugin/split/create
请求方式：POST
请求参数：

参数名	类型	是否必填	描述	示例值
merchant_no	String	是	商户号	20250001
out_trade_no	String	是	原支付订单商户号	20251124001
split_rule	String	是	分账规则（JSON 格式，支持多主体分账）	[{“payee_no”:”P2025001″,”ratio”:0.7,”desc”:”供应商分账”},{“payee_no”:”P2025002″,”ratio”:0.3,”desc”:”平台分账”}]
split_desc	String	否	分账描述	测试分账
sign	String	是	签名值	E88889999000011112222333344445555

响应数据（code=200）：

json

{
  "code": 200,
  "msg": "分账订单创建成功",
  "data": {
    "split_order_no": "S2025112400001",  // 分账订单号
    "out_trade_no": "20251124001",
    "total_amount": 100.00,
    "split_status": "PENDING",          // 分账状态：PENDING=待分账，PROCESSING=分账中，SUCCESS=分账成功，FAILED=分账失败
    "create_time": "2025-11-24 10:10:00"
  },
  "sign": "xxx"
}

沙箱测试环境使用说明

沙箱环境用于接口联调测试，无真实资金流转，支持模拟支付成功、退款成功等场景；
沙箱环境商户号与 API 密钥需单独申请（联系客户经理获取）；
测试支付时，可使用官方提供的测试账号（如微信支付测试号、支付宝沙箱账号）完成支付；
沙箱环境回调地址支持 http 协议（仅测试用），正式环境需使用 https 协议。

常见问题

1. 签名验证失败怎么办？

检查参数是否按 ASCII 字典序排序；
核对是否遗漏参数（如 merchant_no）或参数值为空；
确认 api_key 是否正确（正式环境与沙箱环境密钥不同）；
检查金额格式是否保留 2 位小数（如 100 需改为 100.00）。

2. 支付回调未收到怎么办？

检查 notify_url 是否公网可访问（可通过 Postman 测试）；
核对回调地址是否与商户后台配置一致；
查看商户后台「回调日志」，确认是否存在回调失败记录（如签名错误、响应格式错误）；
确保服务器未拦截彩虹易支付回调 IP（联系技术支持获取回调 IP 段）。

3. 接口调用频率超限怎么办？

优化代码逻辑，减少不必要的重复查询（如订单查询可定时轮询，而非实时调用）；
联系客户经理申请提升调用频率阈值；
对高频接口（如订单查询）实现本地缓存，降低 API 调用次数。

技术支持

文档更新：本文档将随系统版本迭代更新，建议定期查看官方文档中心；
问题咨询：7×24 小时技术支持热线QQ：1502026362；
接口联调：如需技术人员协助联调，可通过商户后台「工单系统」提交需求；
插件定制：如需定制化插件接口，可联系客户经理沟通需求。