Epay Protocol
兼容常见易支付
标准面板换网关和密钥即可切换。原生统一下单、退款接口见支付 API 文档。
1
. 怎么切过来
本文是 epay（易支付）兼容协议，和「支付 API 文档」里的统一下单 / 退款 / 重定向不是同一套字段，请不要混用。
标准易支付面板或已按常见 epay 协议对接的充值页，一般只需更换网关地址和商户密钥，原有下单、查单、回调逻辑不用重写。魔改过字段或签名算法的版本，需要对照本文核对差异，不保证覆盖所有二次改造。
你需要准备的
| 项目 | 说明 |
|---|---|
| 网关地址 | 以商户后台展示为准。下文用 `{网关}` 表示，不要写死过期域名。 |
| 商户 ID（pid） | 商户号，后台可查。 |
| 商户密钥（key） | 用于签名与验签，勿泄露、勿提交到前端页面。 |
| 异步通知 notify_url | 支付结果服务端回调，沿用原业务地址即可。 |
| 同步跳转 return_url | 付款完成后浏览器跳转，沿用原业务地址即可。 |
金额、商户订单号、商品名、通道 type 仍按原来的 epay 参数提交。建议先用小额订单联调，确认通知与查单一致后再放量。
常见接口路径
| 用途 | 相对路径 | 说明 |
|---|---|---|
| 页面跳转支付 | `/submit.php` | 浏览器 GET/POST 跳转收银台或通道页面。 |
| API 下单 | `/mapi.php` | 服务端请求，返回支付链接或二维码等。 |
| 查询订单 | `/api.php` | 按商户订单号查询支付状态。 |
完整地址为 {网关} + 相对路径，例如 {网关}/submit.php。若后台给出的网关已含路径，以后台为准。
2
. 签名
与常见彩虹易支付一致：对参与签名的参数按参数名 ASCII 升序排列，拼接后接上商户密钥，再做 MD5（小写）。sign、sign_type 以及空值不参与签名。
步骤
第一步： 取出全部非空参数。排除 sign、sign_type。按参数名从小到大排序。
第二步： 拼成 key1=value1&key2=value2&…（最后一项后面没有 &）。
第三步： 在该字符串末尾直接拼接商户密钥 key（中间不加 &key=）。
第四步： 对结果做 MD5，得到 32 位小写十六进制，作为 sign。请求里同时带 sign_type=MD5。
验签时用收到的参数按同样规则重算，再与传入的 sign 比较。接口以后可能增加字段，验签必须忽略未知字段之外的空值和 sign 本身。
示例
pid=1001type=alipayout_trade_no=P20260917001name=账户充值money=1.00notify_url=https://your.example/notifyreturn_url=https://your.example/return待签名串形态：money=1.00&name=账户充值¬ify_url=…&out_trade_no=P20260917001&pid=1001&return_url=…&type=alipay + 商户密钥。
实际签名值随密钥变化，请用后台密钥在本地按上述步骤计算，不要复制示例里的假密钥。
3
. 发起支付
请求参数
| 参数 | 必填 | 说明 |
|---|---|---|
| pid | 是 | 商户 ID。 |
| type | 是 | 支付通道，见「通道 type」。 |
| out_trade_no | 是 | 商户订单号，需保证商户内唯一。 |
| notify_url | 是 | 异步通知地址，需公网可访问。 |
| return_url | 是 | 支付完成同步跳转地址。 |
| name | 是 | 商品名称 / 订单标题。 |
| money | 是 | 金额，单位元，最多两位小数，例如 `1.00`。 |
| sitename | 否 | 网站名称，部分面板会展示。 |
| param | 否 | 透传参数，通知时原样返回（若通道支持）。 |
| sign | 是 | 签名。 |
| sign_type | 是 | 固定 `MD5`。 |
页面跳转 `/submit.php`
用浏览器 GET 或表单 POST 提交到 {网关}/submit.php。用户会被带到收银台或对应通道页面完成付款。
API 下单 `/mapi.php`
服务端以 GET/POST 提交相同参数到 {网关}/mapi.php。成功时返回 JSON，常见字段：
| 字段 | 说明 |
|---|---|
| code | `1` 表示下单成功，其它为失败。 |
| msg | 失败原因或提示。 |
| trade_no | 平台订单号（若返回）。 |
| payurl | 可跳转的支付链接。 |
| qrcode | 扫码内容 / 二维码链接（若返回）。 |
| urlscheme | 唤起 App 的 scheme（若返回）。 |
优先按返回里实际出现的字段跳转或展示二维码。不要假设每次都同时返回 payurl 和 qrcode。
4
. 查单
付款后请以异步通知为准，同时可用查单做掉单补查。请求 {网关}/api.php。
| 参数 | 必填 | 说明 |
|---|---|---|
| act | 是 | 固定 `order`。 |
| pid | 是 | 商户 ID。 |
| key | 是 | 商户密钥。部分实现用 sign 代替明文 key，以联调结果为准。 |
| out_trade_no | 是 | 商户订单号。 |
成功时 JSON 常见字段：
| 字段 | 说明 |
|---|---|
| code | `1` 查询成功。 |
| trade_no | 平台订单号。 |
| out_trade_no | 商户订单号。 |
| type | 支付通道。 |
| pid | 商户 ID。 |
| addtime | 创建时间。 |
| endtime | 完成时间。 |
| name | 商品名称。 |
| money | 金额（元）。 |
| status | `1` 已支付，`0` 未支付。 |
只有查单或通知均显示已支付，才给用户加余额、发货。不要只凭同步跳转页面判断成功。
5
. 异步通知与同步跳转
异步通知 notify_url
支付成功后，平台以 GET（常见）请求你的 notify_url。参数与下单字段对应，并带 sign、sign_type。
| 参数 | 说明 |
|---|---|
| pid | 商户 ID。 |
| trade_no | 平台订单号。 |
| out_trade_no | 商户订单号。 |
| type | 支付通道。 |
| name | 商品名称。 |
| money | 订单金额（元）。 |
| trade_status | 常见为 `TRADE_SUCCESS`。 |
| param | 下单时的透传参数（若有）。 |
| sign | 签名。 |
| sign_type | `MD5`。 |
处理步骤：
1. 按本文「签名」规则验签。
2. 核对 out_trade_no、money 与本地订单一致。
3. trade_status 为成功且本地尚未入账时，完成业务（加余额、发货等），保证幂等。
4. 处理成功后，HTTP 响应正文输出 success（小写）。其它内容会被视为失败并可能重试。
同步跳转 return_url
用户支付完成后浏览器跳转到 return_url，参数与通知类似。同步跳转只用于展示结果页，不能单独作为入账依据。入账必须以异步通知或查单为准。
6
. 通道 type
常见取值如下。以商户后台实际开通的通道为准，未开通的 type 会下单失败。
| type | 说明 |
|---|---|
| alipay | 支付宝 |
| wxpay | 微信支付 |
| qqpay | QQ 钱包（若开通） |
| bank | 网银 / 其它（若开通） |
后台若使用自定义通道标识，按后台文档或顾问提供的取值提交，不要自行猜测。
7
. 注意
• 网关、pid、密钥只从商户后台获取，不要使用过期或第三方转发的地址。
• 本协议与 支付 API 文档 相互独立：那边是 userId / outTradeNo 等原生字段，这边是 pid / out_trade_no。
• 标准易支付一般换网关即可通；增删字段、改签名、改金额单位的魔改面板需要对照联调。
• 金额单位为元（如 1.00），不是原生支付 API 文档里的「分」。
• 生产环境请使用 HTTPS。密钥仅放在服务端。
• 联调问题可联系顾问，按实际请求报文核对。