接口模型

OPS 不强制平台放弃传统易支付接口。平台可以继续使用 submit.php、mapi.php、api.php 等入口，但必须通过配置发现说明这些入口的语义和字段映射。

支付创建

支付创建用于商户发起一笔支付订单。传统易支付平台通常通过浏览器表单提交到 submit.php，接口型平台可以通过 mapi.php 或 JSON API 创建订单。

标准字段

OPS 字段	易支付兼容字段	类型	必填	说明
merchant_id	pid、mch_id	string	是	商户编号
payment_method	type	string	是	支付方式，例如 alipay、wxpay
merchant_order_no	out_trade_no	string	是	商户订单号，同一商户下必须唯一
subject	name	string	是	商品或订单标题
amount	money	string	是	订单金额，十进制字符串
notify_url	notify_url	string	是	异步通知地址
return_url	return_url	string	否	同步跳转地址
client_ip	clientip	string	否	用户客户端 IP
metadata	param	string	否	商户透传参数
sign_type	sign_type	string	否	签名方式，未传时按配置默认值
sign	sign	string	是	请求签名

传统表单提交

POST /submit.php HTTP/1.1
Content-Type: application/x-www-form-urlencoded

pid=1000&type=alipay&out_trade_no=ORDER202606140001&name=Test&money=9.90&notify_url=https%3A%2F%2Fmerchant.example.com%2Fnotify&return_url=https%3A%2F%2Fmerchant.example.com%2Freturn&sign_type=MD5&sign=...

平台可以支持 GET，但标准推荐 POST。当 GET 与 POST 都支持时，.well-known 配置中的 transports.payment_create 必须同时声明。

接口下单响应

接口型下单推荐返回 JSON。

{
  "code": 0,
  "message": "success",
  "data": {
    "platform_order_no": "202606142200001",
    "merchant_order_no": "ORDER202606140001",
    "pay_url": "https://pay.example.com/pay/202606142200001",
    "qrcode": "https://pay.example.com/qr/202606142200001",
    "expires_at": "2026-06-14T10:00:00+08:00"
  }
}

兼容易支付旧实现时，平台也可以返回 HTML 表单、跳转地址、纯文本错误或旧格式 JSON，但必须在配置中声明响应格式。

异步通知

异步通知是支付结果确认的唯一可信来源。同步返回只用于用户体验，不应用于最终入账。

通知字段

OPS 字段	易支付兼容字段	类型	必填	说明
platform_order_no	trade_no	string	是	平台订单号
merchant_order_no	out_trade_no	string	是	商户订单号
merchant_id	pid	string	是	商户编号
payment_method	type	string	是	支付方式
subject	name	string	否	商品或订单标题
amount	money	string	是	支付金额
status	trade_status	string	是	支付状态
metadata	param	string	否	商户透传参数
sign_type	sign_type	string	否	签名方式
sign	sign	string	是	通知签名

通知确认

商户验签通过，并确认商户订单号、金额、支付状态均符合预期后，必须返回纯文本：

success

平台收到其他响应时可以重试通知。重试策略由平台决定，但建议使用递增间隔，至少重试 6 次。

同步返回

同步返回发生在用户浏览器跳转到 return_url 时。同步返回可以携带与异步通知类似的字段，但商户不能只依赖同步返回完成订单。

同步返回的推荐用途：

• 展示支付结果。
• 引导用户返回业务系统。
• 触发前端轮询订单查询。

同步返回的禁止用途：

• 未验签直接修改订单状态。
• 未校验金额直接发货。
• 替代异步通知。

订单查询

订单查询用于补偿异步通知丢失、前端状态刷新和人工排查。

查询请求

传统易支付平台常见请求：

GET /api.php?act=order&pid=1000&out_trade_no=ORDER202606140001&sign_type=MD5&sign=...

兼容平台可以使用 act=order、act=query 或独立查询端点。实际取值必须在配置的 compatibility.query_act_values 中声明。

查询响应

{
  "code": 0,
  "message": "success",
  "data": {
    "platform_order_no": "202606142200001",
    "merchant_order_no": "ORDER202606140001",
    "amount": "9.90",
    "payment_method": "alipay",
    "status": "paid",
    "paid_at": "2026-06-14T09:31:20+08:00"
  }
}

状态映射

OPS 状态	易支付常见值	说明
pending	WAIT_BUYER_PAY、0	待支付
paid	TRADE_SUCCESS、TRADE_FINISHED、1	已支付
closed	TRADE_CLOSED、-1	已关闭
refunding	REFUNDING	退款中
refunded	REFUNDED、2	已退款
failed	FAILED	支付失败

平台可以返回旧状态值，但配置中必须声明哪些值等价于支付成功。

退款与关闭订单

退款和关闭订单属于扩展能力。平台支持时，应在配置中提供 endpoints.refund 和 endpoints.close。

退款请求推荐字段：

字段	类型	必填	说明
merchant_id	string	是	商户编号
merchant_order_no	string	否	商户订单号
platform_order_no	string	否	平台订单号
refund_order_no	string	是	商户退款单号
refund_amount	string	是	退款金额
reason	string	否	退款原因
sign_type	string	否	签名方式
sign	string	是	签名

merchant_order_no 与 platform_order_no 至少提供一个。

错误响应

标准 JSON 错误响应：

{
  "code": 40001,
  "message": "invalid signature",
  "request_id": "req_202606140930001"
}

常见错误码：

错误码	说明
40001	签名错误
40002	缺少必填字段
40003	支付方式不支持
40004	金额格式错误
40005	商户不存在或不可用
40006	商户订单号重复
40401	订单不存在
50001	平台内部错误