# 易支付协议兼容接入（已有插件的系统怎么切过来）

> docId：`XD-OP-13` ｜ version：`1.0.0` ｜ status：`PUBLISHED`

这一篇是给**系统里已经装了「易支付 / 彩虹支付」类支付插件**的商家看的：不改你系统的代码，只把三个值填进插件配置，就能用小豆的收银链收钱。

先划清一件事（很重要）：**「易支付」「彩虹支付」在这里都是行业叫法，指同一类用共享密钥签名、参数固定的老式收款协议**（这一类协议最常见的实现叫「彩虹易支付」，插件商常直接把它叫「易支付」）。 我们不是「免签 / 第四方代收」那一类做法——买家付的钱由**有支付牌照的支付公司**收付与结算，进的是**你自己在该支付公司开的结算账户**，钱不经过任何中间人的账户。两者的资金路径详见 [README 的 FAQ](../README.md#常见问题faq)。

## 1. 三个值，两个入口

在卖家后台的「**易支付接口配置**」页开通后，你会拿到三个值：

| 值 | 是什么 | 填到哪 |
| --- | --- | --- |
| **网关地址** | 收款入口地址（系统按插件类型要完整地址或基址，页面上有对照表） | 你系统「易支付」配置里的网关 / 接口地址 |
| **商家 ID** | 平台给你的商户号（PID） | 插件配置里的 PID / 商户号 |
| **商户密钥** | 与商家 ID 配对的一串密钥 | 插件配置里的密钥 / Key |

- 开通只需一次，**不用写代码**；密钥在页面上默认只显示尾部，点「查看完整密钥」要做一次短信验证，明文短时展示、请当场复制到你自己的服务器。
- 密钥**等同于收款凭证**：只填进你自己的服务器，不要发在群里、工单里或截图里。怀疑泄露就去页面点「重置密钥」——旧密钥**立即失效**，商家 ID 不变。

## 2. 协议长什么样

**兼容该协议的多种接口**：`submit.php`（表单提交收单）、`mapi.php`（程序化收单）与 `api.php`（查询；`act=order` / `act=query`）。你的插件原来把请求发给哪个入口，就还发给哪个入口——三类接口的参数与签名规则完全一样，不用挑、也不用迁移。

### 2.1 两个建单入口

| 你的插件怎么发请求 | 会得到什么 |
| --- | --- |
| **表单提交**（浏览器跳转语义）：把参数提交到网关地址 | 平台返回一个跳转，落到收银页；买家在那里用支付宝扫码付款 |
| **程序化请求**：在同一网关域名下用 `mapi.php` 发同样的参数 | 返回 JSON（含收银页地址；支付宝订单还会带官方收款码内容，能直接画成二维码） |

两边参数完全一样，只是返回形式不同——你的插件原来怎么发，就还怎么发。

### 2.2 建单参数

| 参数 | 要求 |
| --- | --- |
| `pid` | 必填：上面那个**商家 ID** |
| `out_trade_no` | 必填：你自己的订单号，**6–64 位**，只能用大小写字母、数字、下划线和短横线（**不支持点号**） |
| `money` | 必填：金额，元为单位的十进制写法（`1.1` 和 `1.10` 都行），**最低 0.01 元**；单笔上限以你应用当前的额度为准 |
| `name` | 必填：商品名（会出现在收银页上） |
| `notify_url` | 必填：支付成功后我们**异步通知**你的地址，必须是 **https** 开头的完整地址 |
| `return_url` | 选填：支付完成后买家**同步跳回**你页面的地址，同样必须 **https**；不填就用平台的完成页 |
| `type` | 选填：`alipay` / `wxpay`；**不填**时按你在配置页选的默认支付方式走 |
| `param` | 选填：你自己的透传参数，会原样带回通知与回跳 |
| `sign` / `sign_type` | 签名与签名类型（见下；`sign_type` 不填按 `MD5`） |

其余字段（`device`、`sitename` 这类插件习惯带的）**带着不会报错**，我们按签名规则处理、内容忽略。

### 2.3 签名怎么算

和这类插件的通用做法一致（这也是为什么你的插件不用改）：

1. 把所有参数（**除 `sign`、`sign_type`**）按键名的 ASCII 顺序排好；
2. 丢掉值为空的参数；
3. 拼成 `键=值&键=值` 的串（值**不额外编码**）；
4. 把这个串**直接接上你的商户密钥**（中间没有分隔符），算 **MD5**，取**小写**十六进制。

收到的通知、回跳我们也用同一个算法签名，你按同样的规则验一遍即可。

### 2.4 支付结果怎么拿

- **异步通知**：支付成功后我们用 **GET** 请求你填的 `notify_url`，参数含 `trade_status=TRADE_SUCCESS`、你的 `out_trade_no`、平台的 `trade_no`、金额等，并带签名。**你返回纯文本 `success`** 我们就认为送达；否则会按退避节奏重发（第一次即时，之后按分钟级到小时级逐档拉长，最多 8 次）。**通知可能重复到达**，请按 `out_trade_no` 幂等处理。
- **同步回跳**：买家用支付宝付完会跳回你填的 `return_url`（带同一套参数与签名）。注意：**跳回来只说明流程走完了，不代表付款成功**——付款成功只认异步通知或查单结果。
- **主动查询**：在网关域名下用 `api.php`，`act=order`（按订单号查一笔）或 `act=query`（查商户状态）可查；返回里 `status` 为 1 表示已支付。

### 2.5 重复提交同一个订单号会怎样

| 情况 | 结果 |
| --- | --- |
| 未支付、金额一致 | 按原订单返回（不会建出两笔） |
| 未支付、金额不一致 | 拒绝（订单号已存在） |
| 已支付 | 拒绝（订单已支付） |
| 已关闭 | 拒绝，**请换一个新订单号** |

## 3. 支持范围

| 支付方式 | 状态 |
| --- | --- |
| **支付宝** | 现在就能接（买家扫收银页上的码付款） |
| **微信** | **微信 JSAPI 已开放**：买家在微信内打开收银页即可调起微信支付（仅限微信内浏览器；微信外手机浏览器与商家 App 内没有「直接拉起」形态）。其他通道或交易形态是否放行以对接人确认为准；未放行时下单会返回一个**正常的、可预期的拒绝**，别当故障、更别反复重试 |
| **QQ 钱包** | **不支持**：你的插件里如果选了它，请改成支付宝或微信 |

## 4. 这一篇不覆盖什么（明确不做）

- 只支持上面这种**共享密钥签名**的老式协议；**不支持**带 RSA 密钥对的新形态（要用它请走[接入指南](./02-integration-guide.md)的七接口）。
- **不支持**当 API 调你的退款：退款走商家后台「成交订单」或[退款与对账](./08-refund-and-reconciliation.md)那条链。
- **不支持**批量查询、修改结算账户、二维码直出等边角能力。
- 你系统里原有的「免签 / 第四方代收」类网关**不在迁移范围**——我们不接入也**不充当**那类通道（见 [README 的 FAQ](../README.md#常见问题faq)）。

## 5. 上线前自检

1. 用**你自己系统**下第一笔**小额真实订单**（金额尽量小），确认能跳到收银页并正常付款；
2. 付完后：你的订单被标记为已支付、`notify_url` 收到一条验签通过的通知（记得回 `success`）、同步回跳把你带回了订单页；
3. 回到卖家后台「易支付接口配置」页，确认密钥的「最后使用时间」刚刚更新过。

费率与到账口径与开放平台**同一条资金链**，见[费率与限额](./07-fees-and-limits.md)；上线清单逐条自检见[上线检查清单](./11-go-live-checklist.md)。