开发文档
佳梦云付对外接口兼容标准聚合支付协议。已有多数聚合支付生态的商户零改造迁移； 新接入的开发者按本文档 10 分钟可完成联调。
1. 接入概述
商户在商户中心注册后，在「应用与密钥」创建应用，获得对接三要素：APPID（应用标识）、商户私钥（对下单/查单/退款/代付请求做 RSA2 签名）与平台公钥（验签平台异步通知与同步回跳）。 支付流程：用户在商户站发起支付 → 商户服务端组装参数签名 → 请求下单接口/api/pay/create→ 商户将返回的收银台地址渲染成二维码（或跳转）→ 用户扫码在平台收银台完成支付 → 平台异步通知商户 → 商户凭通知发货。
安全准则：一切以异步通知与服务端查询结果为准，同步回跳仅用于展示；密钥只保存在服务端，不要下发到前端。
平台单号（trade_no）与 JMY 前缀
平台订单号 trade_no以可配置前缀开头（默认 JMY，后台「系统设置 → 订单与商品 → 平台订单号前缀」可改，1-8 位字母数字）， 后接下单时间戳（年月日时分秒 + 毫秒）与 4 位随机十六进制段，全局唯一，如JMY20260930153045123A1B2。 提交给微信/支付宝的渠道商户订单号统一使用该前缀的平台单号（回调/查单/退款锚定口径一致）； 商户单号 out_trade_no 仅平台内部留存对账。
订单状态说明
| 0 | 待支付 | 订单已创建，等待用户支付 |
| 1 | 已支付 | 用户已完成支付，商户可发货；余额按费率入账 |
| 2 | 已退款 | 订单金额已退回付款人，商户余额相应扣减 |
| 3 | 已关闭 | 超时未支付自动关闭 |
| 4 | 已冻结 | 投诉工单冻结，商户余额已扣减对应金额 |
| 5 | 待核查 | 订单待平台核查，商户余额已冻结扣除；核查通过解冻退回，核查成立转退款 |
2. 签名规则（RSA2）
平台采用双密钥 RSA2 签名体系：请求侧由商户用商户私钥对参数串做 RSA2（SHA256withRSA）签名；通知/回跳侧由平台用平台私钥签名，商户用平台公钥验签。 两侧待签名串构造规则一致：参与签名的参数按参数名 ASCII 码从小到大排序，以k=v&k=v拼接（跳过空值、sign、sign_type）。密钥的获取与保管见应用认证。
待签名串 = "app_id=ATLJIHI91&money=9.90&name=会员月卡¬ify_url=https://...&out_trade_no=SHOP1&type=alipay"
sign = base64(RSA2签名(待签名串, 商户私钥)) // 请求携带 sign_type=RSA2 与 timestamp（±300 秒防重放）平台收到请求后用该应用的商户公钥（创建应用时商户上传/平台生成并留存的那一把）验签； 任何字段被篡改都会导致验签失败。商户私钥只保存在商户自己的服务端，平台不留存、遗失只能重置。
3. 支付下单（唯一对接方式）
平台仅提供 API 下单一种对接方式：/api/pay/create（GET/POST，与 /api/pay/query、/api/pay/refund 同族命名）。下单成功返回平台收银台地址（微信/支付宝内收银台），由收款方（对接站点）自行渲染二维码； 付款人用微信/支付宝扫码后进入平台收银台，核验订单信息并在微信/支付宝内完成支付。 平台不提供页面跳转式对接。
| 参数名 | 必填 | 说明 |
|---|---|---|
| app_id | 是 | 应用 ID，商户中心「应用与密钥」创建（见「应用认证」） |
| type | 是 | 支付方式：wechat（微信支付）/ alipay（支付宝），平台按商户可用通道自动解析 |
| out_trade_no | 是 | 商户订单号，1-64 位，商户内唯一 |
| notify_url | 是 | 异步通知地址，http(s):// |
| return_url | 否 | 支付完成后的同步回跳地址 |
| name | 是 | 商品名称，最长 100 字 |
| money | 是 | 金额（元），最多两位小数，如 9.90 |
| param | 否 | 业务扩展参数，支付后原样随异步通知返回，最长 200 字 |
| clientip | 否 | 用户发起支付的 IP 地址（平台记录用于风控比对） |
| device | 否 |
4. 异步通知（notify_url）
支付成功后，平台以 GET 方式携带以下参数请求 notify_url，商户验签通过并处理完成后输出success即表示送达；最多重试 5 次，也可在商户中心手动重发。 通知由平台私钥对参数串做 RSA2（SHA256withRSA）签名（sign_type=RSA2），商户用平台公钥验签，待签名串构造规则与请求侧一致（ASCII 升序，跳过空值与 sign/sign_type）。
| 参数名 | 必填 | 说明 |
|---|---|---|
| payStatus | — | 支付状态：1 支付成功 / 2 已退款（退款通知，trade_status=TRADE_CLOSED） |
| trade_status | — | 交易状态：TRADE_SUCCESS / TRADE_CLOSED |
| tradeNo | — | 平台订单号 |
| outTradeNo | — | 商户订单号 |
| name | — | 商品名称 |
| money | — | 金额（元） |
| param | — | 提交时透传的 param（如有） |
| sign | — | 签名：平台私钥对参数串的 RSA2 签名（base64），用平台公钥验签 |
| sign_type | — | 签名类型：固定 RSA2 |
5. 同步回跳（return_url）
用户支付完成后浏览器将跳转 return_url，携带与异步通知一致的签名参数（payStatus、trade_status、tradeNo、outTradeNo、name、money、param、sign 及 sign_type）。 仅用于向用户展示结果，发货逻辑必须以异步通知或主动查询为准；如需校验，验签方式与异步通知一致（平台公钥 RSA2）。
6. 订单查询
/api/pay/query（GET/POST）： 传 app_id、trade_no 或 out_trade_no、sign、sign_type=RSA2、timestamp（可选，±300 秒防重放） （应用认证同款验签）。 返回 code=1 时 status 与订单状态说明一致（0 待支付 / 1 已支付 / 2 已退款 / 3 已关闭 / 4 已冻结 / 5 待核查），endtime 为支付时间戳（未支付为 0）。
返回字段说明：
| 参数名 | 必填 | 说明 |
|---|---|---|
| code | — | 1 为成功，-4 为订单不存在 |
| pid | — | 商户 ID（数字） |
| trade_no | — | 平台订单号 |
| out_trade_no | — | 商户订单号 |
| type | — | 支付方式 |
| name | — | 商品名称 |
| money | — | 订单金额（元，两位小数） |
| status | — | 订单状态（见「订单状态说明」） |
| addtime | — | 下单时间戳（秒） |
| endtime |
7. 应用认证（AppID + RSA2 签名）
平台接口统一采用应用级认证：在商户中心「应用与密钥」创建应用后，提交参数中 用 app_id 替代 pid， 并以商户私钥对参数串做 RSA2（SHA256withRSA）签名：sign_type=RSA2、sign为签名结果的 base64 字符串（平台用留存的应用公钥验签）。 早期的 sk_ 应用密钥（app_secret）已废弃，不再支持。
POST /api/pay/create
app_id=ATLJIHI91&type=alipay&out_trade_no=SHOP1
¬ify_url=...&name=会员&money=9.90
&sign=base64(RSA2签名(排序参数串, 商户私钥))&sign_type=RSA2一个应用可绑定多个渠道；停用应用后其全部请求立即失效。适合多业务线隔离密钥的场景。
- APPID：应用标识，请求中以 app_id 携带，应用设置页长期可查；
- 商户私钥（RSA2，PKCS#8 PEM）：只保存在商户自己的服务端，用于对请求加签，请勿外泄；仅在创建/重置应用时的弹窗展示一次，平台不留存，遗失只能重置密钥；
- 商户公钥（RSA2，SPKI PEM）：留存于平台，用于校验商户请求签名；
- 平台公钥（RSA2，SPKI PEM，全局一对）：随创建/重置弹窗一并提供；订单的异步通知/同步回跳由平台私钥 RSA2 签名（sign_type=RSA2，见「异步通知」章节），商户侧用平台公钥验签（PHP openssl_get_publickey 对 SPKI/PKCS#1 均可加载，请原样保存完整 PEM）。
RSA2 签名规则：参与签名的参数按 ASCII 升序以k=v&拼接， 跳过空值与 sign/sign_type；随后用商户私钥对该串做 RSA2（SHA256withRSA）签名， 签名结果取 base64 作为 sign 参数提交（sign_type=RSA2）。
- 异步通知地址 / 同步跳转地址：配置后覆盖请求中的 notify_url / return_url，防止地址被篡改。
- 请求 IP 白名单：配置后仅允许名单内 IP 以该应用下单（支持单 IP 与网段）。
- 域名白名单：未配置应用级通知地址时，请求携带的通知/跳转域名必须在名单内。
- 重新通知：对该应用最近 10 笔已支付订单一键补发异步通知（需先配置异步通知地址）。
8. 退款
商户中心「订单管理 → 订单详情 → 发起退款」支持全额/部分退款；也可调用接口：POST /api/pay/refund（GET/POST 表单均可；平台自有协议，应用模式 app_id + RSA2 签名，需开通退款产品）。
| 参数名 | 必填 | 说明 |
|---|---|---|
| app_id | 是 | 应用 ID（应用认证，见「应用认证」章节；RSA2 签名，可携带 timestamp 防重放） |
| trade_no | 二选一 | 平台订单号（JMY 前缀） |
| out_trade_no | 二选一 | 商户订单号（与 trade_no 至少携带其一，先按平台单号匹配再回退商户单号） |
| money | 否 | 退款金额（元），缺省退可退全额；支持部分退款（累计可退 = 应付金额 − 已退金额） |
| out_refund_no | 否 | 退款单号（应用内唯一，缺省由平台生成；用于幂等与对账） |
| reason | 否 | 退款原因，最长 60 字 |
| sign / sign_type | 是 | 商户私钥 RSA2 签名（base64）与固定 RSA2，规则见「应用认证」 |
返回字段说明（成功 code=1）：
| 参数名 | 必填 | 说明 |
|---|---|---|
| code |
9. 代付（转账）
需平台开通「代付」产品。商户中心「代付」页可直接发起（表单操作，自动扣减余额并写流水）； 也可通过开放 API 以应用（app_id + RSA2）发起；渠道侧走微信商家转账到零钱（/v3/transfer/batches） 或支付宝单笔转账（alipay.fund.trans.uni.transfer）。
代付创建：POST /api/transfer/create（GET/POST 表单均可）
| 参数名 | 必填 | 说明 |
|---|---|---|
| app_id | 是 | 应用 ID（应用认证，见「应用认证」章节） |
| out_biz_no | 是 | 商户代付单号，1-64 位，应用内唯一（幂等键：重复提交返回既有代付单，不重复执行/扣款） |
| transfer_type | 是 | 代付方式：alipay / wechat / bank（bank 需平台配置对应通道） |
| payee_account | 是 | 收款账号：微信为用户 openid，支付宝为登录号/UserId，银行卡为卡号 |
| real_name | 否 | 收款人实名（微信代付必填用于核对），最长 30 字 |
| money | 是 | 代付金额（元），最多两位小数，单笔不低于 1.00 |
| notify_url | 否 | 代付结果异步通知地址，http(s)://；应用级通知地址配置后覆盖 |
| remark | 否 | 转账备注（展示在账单），最长 60 字 |
| timestamp |
10. SDK 下载
官方 SDK 内置签名、支付提交、订单查询与异步通知验签，零依赖直接引入；包内含 README 与可运行示例。
11. 错误码
下单（/api/pay/create）/ 查询 / 退款接口返回 JSON 中的 code 字段；成功时 code=1，失败时为负数错误码并附带 msg。
| 参数名 | 必填 | 说明 |
|---|---|---|
| 1 | — | 成功（查询接口返回；订单状态另见 status 字段） |
| -1 | — | 参数错误：字段缺失或格式不正确、通知域名不在应用白名单内、runmode 与应用运行模式不一致（提示信息会点名两侧应改为生产/沙盒） |
| -2 | — | 应用不存在或已停用（app_id 填写错误，或应用被手动停用） |
| -3 | — | RSA2 验签失败：待签名串构造有误、商户私钥不匹配，或未使用 sign_type=RSA2 |
| -4 | — | 支付渠道不可用（type 填写错误或渠道已停用）；查询时为订单不存在 |
| -5 | — | 金额超出范围（下单 0.01 ~ 500,000.00 元）；退款场景为订单未支付或退款金额超过可退金额 |
| -6 | — | 商户订单号重复（同商户下已有待支付/已支付的同号订单） |
| -7 | — | 请求被拒绝：请求 IP 在黑名单内，或不在应用 IP 白名单内 |
| -8 | — | 未开通该支付产品（微信/支付宝/退款需平台开通对应产品） |
| -9 | — | 该支付通道未分配给当前商户（后台「商户管理 → 通道分配」可配置） |
12. 易支付对接插件
与主流易支付插件结构兼容的对接插件（插件名：佳梦云付，目录/标识：jmyfpay）：插件包按主流宿主的识别约定组织——压缩包内是一个文件夹 jmyfpay/，解压出来也是这个文件夹（目录名 = 清单 name）、 清单文件名 info.json、 主类 <Name>Plugin（submit / mapi / notify / return / query / refund / transfer / transfer_query）。 既有易支付生态的开发者可零成本对照；在本平台落为「JSON 清单（epay.json）+ TypeScript 实现（CHANNEL_PLUGINS 注册表）」。
识别约定（与主流易支付一致）
主流易支付宿主按「目录 + info.json + 主类」扫描识别插件，三条缺一不可（旧版包以根目录散放 plugin.json + TS 文件提供，三条均不满足，因此不被识别）：
| 参数名 | 必填 | 说明 |
|---|---|---|
| 目录名 = name | — | 插件目录名必须与 info.json 的 name 一致（jmyfpay 包解压即得 jmyfpay/ 文件夹），宿主按目录扫描 |
| info.json 清单 | — | 文件名固定 info.json；声明 name/title/version/author/desc/icon/pay_types/inputs（type 为 input/select 等主流取值） |
| <Name>Plugin 主类 | — | 文件 <首字母大写 name>Plugin.php，类 extends 宿主 BasePayment，实现 submit/mapi/notify/return/query/refund；配套 <Name>Core.php 承载签名与请求 |
清单字段对照（info.json ↔ epay.json）
包内同时携带两份清单：主流宿主读 info.json， 本平台读 epay.json，字段一一对应：
| 参数名 | 必填 |
|---|
13. 工单接口
商户通过 API 查询与处理售后工单（消费者在收银台发起的售后申请）。鉴权与签名与支付接口一致 （应用模式 RSA2，公共参数 app_id / timestamp / sign / sign_type=RSA2， timestamp 为 10 位秒级、±300 秒防重放）。端点POST /api/open/ticket， 以 act 区分动作：
| 参数名 | 必填 | 说明 |
|---|---|---|
| list | — | 工单列表：返回本应用商户订单关联的工单（分页 page / page_size，默认 20 最大 50）；行字段 bh 工单编号 / ddh 订单号 / type 问题类型 / description 描述 / submit_time 提交时间 / status 状态（处理中、完结、商户申请完结） |
| history | — | 沟通记录：参数 bh（必填）、ddh（建议传，用于归属校验）；返回 rows：sender（user/merchant/platform）、content、time、image |
| reply | — | 商家回复：参数 bh、ddh、content（必填，500 字内）；成功返回 reply_id |
| complete | — | 商家申请完结：参数 ddh；提交后待平台确认（状态转为「商户申请完结」） |
归属校验：工单按订单号关联商户，不属于当前应用商户的工单/订单将被拒绝（403）。响应统一{ code: 0, msg: "success", ... }风格，非 0 为失败。
# 商家回复工单（POST form-urlencoded）
app_id=ATLJIHI91××
timestamp=1791314973
bh=TS20261007001
ddh=JMY20261007000111A1B2
content=已联系用户协商处理，退款将在 24 小时内到账
sign=<RSA2 签名>&sign_type=RSA2
→ { "code": 1, "msg": "success", "reply_id": 128 }14. 投诉查询接口
商户通过 API 查询本应用商户名下的消费者投诉（含渠道同步入库的投诉：微信消费者投诉 2.0、 支付宝消费者投诉、下游易支付系统同步的投诉与售后工单等）。。鉴权同上；端点POST /api/open/complain：
| 参数名 | 必填 | 说明 |
|---|---|---|
| page / page_size | — | 分页：默认 1 / 20，page_size 最大 50 |
| status | — | 可选：0 待处理 / 1 处理中 / 2 已解决；不传返回全部 |
响应 rows 字段：
| 参数名 | 必填 | 说明 |
|---|---|---|
| id | — | 平台投诉单 ID |
| title | — | 投诉标题（含来源与单号，如「彩虹易支付投诉 10001」） |
| content | — | 投诉内容 |
| status / status_label | — | 状态：0 待处理 / 1 处理中 / 2 已解决 |
| trade_no | — | 关联的平台系统订单号（JMY 开头，可空） |
| out_trade_no | — |
15. 工单投诉同步插件（workorder）
对接易支付宿主站（彩虹易支付）用的「工单投诉同步」插件：通过本平台开放接口，把本平台商户的工单与消费者投诉统一视为「投诉」拉取入库， 走宿主站既有的投诉处置链路（自动冻结 / 自动拉黑 / 自动退款 / 事件消息）。插件复用 jmyfpay 通道密钥做鉴权。
| 参数名 | 必填 | 说明 |
|---|---|---|
| 数据来源 | — | 第 13 节 工单接口 POST /api/open/ticket（act=list / history / reply / complete）与第 14 节 投诉查询接口 POST /api/open/complain（act=list） |
| 第三方投诉编号 | — | 9 位随机码（由平台唯一键 crc32 派生，同一投诉恒定 → 重复同步只更新不新增） |
| 类型区分 | — | 工单 → 类型「工单」；平台投诉 → 类型「交易投诉」；同一订单同时存在两者时各存一条 |
| 关联订单号 | — | 优先反查本站 pay_order（api_trade_no / out_trade_no / trade_no 任一命中）；查不到则用接口返回的 out_trade_no（商户单号，19 位）；平台 JMY 单号(21 位)绝不截断写入 |
| 回复 / 完结 | — | 两类都真实回传：工单经 /api/open/ticket act=reply；平台投诉经 /api/open/complain act=reply（真写平台 Complaint.reply）。完结：工单走 act=complete（商户申请完结，待平台确认）；平台投诉到主平台的投诉管理处置主站仅展示 |
| 通道配置（即鉴权凭据） | — | appurl 平台地址（https://pay.avuoo.com）、appid 应用 APPID（商户中心「应用与密钥」创建）、appkey / plat_public_key 平台公钥（验签平台响应）、appsecret / mch_private_key 商户私钥（签名请求） |
| 依赖 | — | 宿主站需已安装彩虹易支付支付插件（epayn，提供 EpayCore RSA 签名客户端） |
| 包内文件 | — | info.json（清单：name=workorder / title=工单投诉同步 / version=2.0.0）、WorkorderPlugin.php、WorkorderTicket.php、README.txt |