易支付系统 · API文档 - 开发文档

易支付系统 · API文档

云枢支付聚合支付系统 · API 文档

版本：V1.0.1　|　兼容彩虹易支付协议（V1 MD5 / V2 RSA2 双签名）

商户中心「API 接口」页可查看并复制：接口地址、商户号（pid）、商户密钥、平台公钥，并自助生成 RSA 密钥对。

一、接入信息

参数	说明
接口地址	`http(s)://你的域名/`（即站点地址 site_url，末尾带 `/`）
商户号 `pid`	商户中心的「商户 ID」
商户密钥 `key`	商户中心「API 接口」页复制（MD5 签名用，可重置）
平台公钥	商户中心「API 接口」页复制（RSA 验签用，验平台回调签名）
商户私钥	RSA 签名时商户自己保存（商户中心生成，仅生成时可见一次）

签名方式二选一（商户中心「签名方式设置」切换）：

MD5（V1，默认）：兼容彩虹易支付老接口；
RSA（V2）：RSA2（SHA256withRSA），商户用私钥签名、平台用商户公钥验签；回调平台用平台私钥签名、商户用平台公钥验签。

二、签名规则

1. 公共规则（MD5 / RSA 相同）

剔除参数中的 sign、sign_type 以及空值参数（注意：值 0 保留）；
剩余参数按键名 ASCII 升序排序；
拼接为 k1=v1&k2=v2&...（URL 编码前的原始值，不 encode）；
MD5：拼接结果后追加 key → md5(k1=v1&...&key)；
RSA：对拼接结果用商户私钥做 SHA256withRSA 签名，sign 传 Base64。

2. 示例

请求参数：

pid=1001
type=alipay
out_trade_no=20230901001
notify_url=https://example.com/notify
return_url=https://example.com/return
name=测试商品
money=0.01

MD5 待签串（key=abcdef1234567890）：

money=0.01&name=测试商品&notify_url=https://example.com/notify&out_trade_no=20230901001&pid=1001&return_url=https://example.com/return&type=alipayabcdef1234567890

sign = md5(待签串)

提示：sign 里的中文等特殊字符按原始 UTF-8 参与签名，不要做 urlencode。

三、下单接口

1. PC 网页收银台：POST submit.php

表单提交（application/x-www-form-urlencoded 或 GET），成功后 302 跳转到收银台页面。

参数	必填	说明
pid	是	商户号
type	是	支付方式：alipay / wxpay / qqpay / unionpay / douyin / gzh / xcx / codepay_alipay / codepay_wxpay / codepay_qqpay 等（以商户中心/后台「支付方式」页为准）
out_trade_no	是	商户订单号，64 位以内
name	是	商品名称，64 位以内
money	是	金额（元，两位小数，0.01 ~ 50000 可配）
notify_url	否	异步回调地址；不传时自动使用商户资料里的默认回调地址（只填网址对接模式）
return_url	否	同步跳转地址
sitename	否	站点名称
param	否	附加参数，回调时原样返回
sign	是	签名
sign_type	否	MD5（默认）/ RSA

2. 移动端 / API 下单：POST mapi.php

JSON 请求体（Content-Type: application/json），返回 JSON：

{
  "code": 1,
  "msg": "下单成功",
  "data": {
    "orderid": "2023090112345612345",
    "trade_no": "2023090112345612345",
    "out_trade_no": "20230901001",
    "type": "alipay",
    "name": "测试商品",
    "money": "0.01",
    "param": "",
    "payurl": "https://你的域名/cashier/2023090112345612345",
    "qrcode": "二维码内容（扫码支付）",
    "jsapi": {},
    "device": "mobile"
  }
}

参数	必填	说明
同上公共参数	—	pid/type/out_trade_no/name/money/sign 必填
device	否	`pc`（默认）/ `mobile`，影响返回结构
openid	否	小程序支付（type=xcx）时传用户 openid

3. GET 下单（SDK 模式）：GET submit.php

GET 携带同样参数（含 sign），返回 JSON（与 mapi.php 相同结构）。

四、查单 / 退款 / 结算：api.php

GET http(s)://你的域名/api.php?act=xxx&...

1. 查单 `act=query`

参数	必填	说明
pid / sign	是	认证参数（同上）
out_trade_no	是	商户订单号

返回：订单状态 status（0 待支付 / 1 已支付 / 2 已结算 / 3 退款中 / 4 已退款 / 5 失败 / -1 已关闭）。

2. 下单 `act=order`

参数与 mapi.php 相同，返回 JSON 下单结果。

3. 退款 `act=refund`

参数	必填	说明
pid / sign	是	认证参数
out_trade_no	是	原订单商户订单号
money	否	退款金额；不传时按剩余可退金额全额退款
reason	否	退款原因（默认「API退款」）
out_refund_no	否	商户退款单号

返回：平台退款单号 refund_no。退款为申请制：提交后进入平台审核，审核通过后向通道发起退款并异步回写。

4. 结算记录 `act=settle`

参数	必填	说明
pid / sign	是	认证参数

返回最近 20 条结算单：settle_no / money / status（0 待处理 / 1 已结算 / 2 已打款 / 3 失败）/ addtime。

五、异步通知

支付成功后，平台向 notify_url POST（表单格式）发送通知：

字段	说明
pid	商户号
trade_no	平台订单号
out_trade_no	商户订单号
type	支付方式
name	商品名称
money	支付金额（两位小数）
trade_status	`TRADE_SUCCESS`
param	下单时透传的附加参数
sign / sign_type	平台签名（MD5 或 RSA）

商户收到通知后：

验签：MD5 商户按同样规则用商户密钥验算；RSA 商户用平台公钥验签（sign_type=RSA）；
校验 trade_status=TRADE_SUCCESS 且金额与订单一致；
业务处理后返回纯文本 success（RSA 通知同样返回 success），否则平台按 1/3/20/60/120 分钟退避重发（最多 10 次，可配）。

六、同步跳转

支付完成后（或用户点击返回），平台 302 跳转到下单时的 return_url，携带 out_trade_no、trade_no、type、name、money、trade_status、sign 等参数，仅作展示，以异步通知为准。

七、返回码约定

code	说明
1	成功（mapi/api 下单类接口）
-1 / 其他	失败，`msg` 为失败原因（如「商户不存在」「签名错误」「支付类型不支持或已停用」「金额超过单笔上限」）

完整线上文档（含各语言 SDK 下载、V1/V2 签名对照示例）：站点 /doc 开发文档站。

八、常见问题

问题	说明
签名错误	确认空值参数已剔除、排序正确、值未做 urlencode；中文按 UTF-8 原文参与签名
只填网址就能对接	商户资料「功能设置」配置默认回调地址后，下单可不传 notify_url，自动使用默认地址
支付类型不可用	后台「支付方式」页停用了该类型，或对应通道未启用
码支付类型	type=codepay_alipay / codepay_wxpay / codepay_qqpay，走个人收款码免签约流程，返回 payurl 为平台收银页
请求被风控拦截	商户/IP 被拉黑或触发下单频率限制，联系平台解除

演示账号机制（2026-09 新增）

支付系统演示站支持「获取演示」：官网演示中心申请后自动生成 24 小时独立后台演示账号。后台管理员表 epay_admin 新增字段 demo_expire（0=非演示账号；大于 0 为过期时间戳），登录时过期账号将被拒绝并提示重新获取。

演示站地址：https://epay.xjukeji.cn　后台：https://epay.xjukeji.cn/admin　获取演示入口：官网产品页「获取演示」按钮或演示中心 /demo。

← 返回文档列表

开发文档