DEVELOPER · API REFERENCE

支付开放接口文档

为已有易支付类集成方式的网站提供可迁移的参数结构。本项目不连接 www.ezfpy.cn，也不会调用真实收单渠道。

开发模式说明

注册商户使用自己生成的 PID 和轮换 KEY 可在本机直接调用兼容沙箱接口；旧版共享 PID 1001 仍默认关闭，仅供测试用。MD5 仅为旧系统迁移兼容，正式业务建议采用新版 HMAC-SHA256、商户身份隔离与官方渠道 SDK。

00 先创建商户自己的支付通道

打开 /auth.html 注册并登录，进入 /channels.html 点击「＋新增」。选择支付宝或微信支付与本地沙箱模式，填写名称、账号标识后保存并启用。在左侧「对接密钥」获取你个人商户 PID，重置后领取一次性展示的 KEY。将网关地址 http://127.0.0.1:5000/、PID 和 KEY 填入你的网站易支付插件配置即可本地联调。

正式通道说明：支付宝官方直连、微信支付官方直连、已授权上游易支付目前只支持保存加密参数，不会向任何真实收款方发送请求。真实支付需要正式签约、官方 SDK 与回调验签、对账后再上线。

01 页面跳转支付

POST /submit.php

接收传统表单参数，验签、匹配商户已启用的同类型沙箱通道后创建 PENDING 演示订单，以 303 重定向到本地收银台页面。不会触发真实付款。

02 API 接口支付

POST /mapi.php

按照商户自行创建的通道匹配 API 下单，演示返回 code、msg、trade_no、out_trade_no、payurl、demo。不返回可支付二维码。

参数	含义	演示取值
pid	商户 ID	商户中心「对接密钥」中显示的个人 PID
type	支付方式	alipay / wxpay
out_trade_no	商户订单号	唯一，3～64 字符
money	交易金额（元）	19.90
name	商品名称	测试商品
notify_url	服务器通知地址	https://your.site/notify
return_url	浏览器返回地址	https://your.site/return
channel_id	可选：指定商户已启用的同类型沙箱通道	CH…
sign	请求签名	MD5 十六进制
sign_type	签名类型	MD5

03 经典签名兼容（仅供迁移）

剔除 sign、sign_type 和空值后，按照 ASCII 键名排序，拼接 key=value，以 & 连接，末尾直接追加商户密钥，再计算 MD5。此方案不适合作为新平台的推荐安全协议。

const raw = Object.entries(params)
  .filter(([k,v]) => !['sign','sign_type'].includes(k) && v !== '')
  .sort(([a],[b]) => a < b ? -1 : a > b ? 1 : 0)
  .map(([k,v]) => `${k}=${v}`).join('&');
const sign = md5(raw + merchantKey);

04 单笔订单查询

POST /api/findorder

查询只允许商户使用自己的 PID/KEY 访问本商户订单。接口需要 PID、商户订单号（type=1）或平台订单号（type=2），并进行同样的签名校验。结果仅包含演示订单状态。

05 支付结果通知

生产环境由支付宝 / 微信支付官方异步回调触发，验签、核对商户和金额、按订单幂等写库后再通知商家 notify_url。回调失败应进入重试队列，浏览器 return_url 只能展示结果、不能确认资金到账。

本项目中的 /api/webhooks/alipay 和 /api/webhooks/wechat 均返回 501，明确标识尚未启用真实验签。

06 新版 HMAC-SHA256 API

提供 POST /api/v1/orders、GET /api/v1/orders/:id。支持带时间戳、nonce、幂等键的 HMAC-SHA256 请求签名；默认同样关闭。

详情请查看项目源代码内的 docs/api.md，并使用本地自动化测试验证接口兼容规则。

07 生产上线前必须完成

支付渠道的实际申请与商户授权、企业与行业资质审核、账户系统和多商户隔离、数据库事务、KYC 处理、密钥托管、风控、主动查单、账单对账以及异常补偿。正式签约完成之前不应承诺个人账户免签约收款。