Appearance
易支付适配
本页定义 OPS 对现有易支付平台的兼容方式。目标是让接入方在面对不同易支付实现时，可以通过统一规则完成下单、查询、通知验签和状态映射。
传统易支付画像
多数易支付平台具备以下特征：
- 支付提交入口为
/submit.php。 - 查询或管理接口为
/api.php。 - 接口下单入口可能为
/mapi.php。 - 商户号字段为
pid。 - 支付方式字段为
type。 - 商户订单号字段为
out_trade_no。 - 商品名字段为
name。 - 金额字段为
money。 - 签名字段为
sign，签名类型字段为sign_type。 - 默认签名算法为 MD5。
- 支付成功通知状态常见为
TRADE_SUCCESS或TRADE_FINISHED。 - 商户通知处理成功后返回纯文本
success。
OPS 平台可以继续保持这些行为，只要通过配置发现把能力声明清楚。
字段映射
| OPS 字段 | 易支付字段 | 备注 |
|---|---|---|
merchant_id | pid | 商户编号 |
payment_method | type | 支付方式 |
merchant_order_no | out_trade_no | 商户订单号 |
platform_order_no | trade_no | 平台订单号 |
subject | name | 商品或订单标题 |
amount | money | 订单金额 |
notify_url | notify_url | 异步通知地址 |
return_url | return_url | 同步返回地址 |
client_ip | clientip | 客户端 IP |
metadata | param | 商户透传参数 |
status | trade_status | 交易状态 |
sign_type | sign_type | 签名方式 |
sign | sign | 签名 |
支付方式映射
| OPS 标识 | 易支付常见值 | 说明 |
|---|---|---|
alipay | alipay、ali | 支付宝 |
wxpay | wxpay、wechat | 微信支付 |
qqpay | qqpay | QQ 钱包 |
bank | bank、unionpay | 网银或银联 |
jdpay | jdpay | 京东支付 |
paypal | paypal | PayPal |
usdt | usdt、trc20、erc20 | 加密货币支付 |
平台存在自定义支付方式时，应在 payment_methods 中增加新条目，不应复用含义不一致的旧标识。
兼容配置模板
一个传统易支付平台的最小 OPS 配置可以这样声明：
json
{
"spec": "Open Payment Specification",
"spec_version": "1.0.0",
"profile": ["OPS-EPAY-1", "OPS-CORE-1"],
"platform": {
"name": "Legacy EPay",
"homepage": "https://pay.example.com",
"charset": "utf-8",
"timezone": "Asia/Shanghai",
"currency": "CNY"
},
"endpoints": {
"submit": "https://pay.example.com/submit.php",
"mapi": "https://pay.example.com/mapi.php",
"api": "https://pay.example.com/api.php",
"query": "https://pay.example.com/api.php?act=order",
"refund": null,
"close": null
},
"transports": {
"payment_create": ["form_post", "form_get"],
"query": ["form_get"],
"notify": ["form_post"]
},
"signing": {
"default": "MD5",
"supported": ["MD5"],
"sign_field": "sign",
"sign_type_field": "sign_type",
"empty_value_policy": "omit",
"sort": "ascii_asc"
},
"payment_methods": [
{
"code": "alipay",
"name": "支付宝",
"aliases": ["alipay"],
"scenes": ["pc", "wap", "qr"],
"enabled": true
},
{
"code": "wxpay",
"name": "微信支付",
"aliases": ["wxpay"],
"scenes": ["pc", "wap", "qr"],
"enabled": true
},
{
"code": "qqpay",
"name": "QQ 钱包",
"aliases": ["qqpay"],
"scenes": ["pc", "wap", "qr"],
"enabled": true
}
],
"fields": {
"merchant_id": ["pid"],
"payment_method": ["type"],
"merchant_order_no": ["out_trade_no"],
"platform_order_no": ["trade_no"],
"subject": ["name"],
"amount": ["money"],
"notify_url": ["notify_url"],
"return_url": ["return_url"],
"client_ip": ["clientip"],
"metadata": ["param"],
"status": ["trade_status"]
},
"callbacks": {
"notify_success_body": "success",
"return_url_trusted": false
},
"compatibility": {
"query_act_values": ["order", "query"],
"success_status_values": ["TRADE_SUCCESS", "TRADE_FINISHED", "1"]
}
}配置发现失败时的推断
为了兼容尚未提供 OPS 配置的老平台，客户端可以在用户明确选择“传统易支付模式”时按以下规则推断：
| 能力 | 默认推断 |
|---|---|
| 提交地址 | {base_url}/submit.php |
| 接口下单 | {base_url}/mapi.php |
| 通用接口 | {base_url}/api.php |
| 查询接口 | {base_url}/api.php?act=order |
| 签名方式 | MD5 |
| 支付方式 | alipay、wxpay、qqpay |
| 字符集 | utf-8 |
| 通知成功响应 | success |
该推断只用于兼容，不应作为 OPS 平台的正式能力声明。平台接入 OPS 后必须提供 .well-known 配置。
下单适配流程
- 读取配置中的
fields，确定实际提交字段名。 - 读取
payment_methods，把用户选择的标准支付方式映射为平台接受的别名。 - 使用配置中的
signing.default计算签名。 - 根据
transports.payment_create选择form_post、form_get或接口提交。 - 如果返回跳转地址，客户端引导用户访问该地址。
- 如果返回二维码，客户端展示二维码并轮询订单查询接口。
通知适配流程
- 接收通知参数。
- 根据
fields把易支付字段映射为 OPS 字段。 - 根据
signing重算签名并比较。 - 将
trade_status映射为 OPS 状态。 - 校验订单号、金额、商户号。
- 幂等更新订单。
- 返回配置中声明的
callbacks.notify_success_body。
平台侧改造建议
传统易支付平台最小改造只需要新增一个配置接口：
txt
GET /.well-known/openpayment-configuation第一阶段不需要改动下单、查询和通知接口。平台只要把现有能力声明出来，就能降低接入方试错成本。
第二阶段建议补充：
- 标准 JSON 查询响应。
- HMAC-SHA256 签名。
- 支付方式可用性开关。
- 订单关闭和退款接口。
- 通知重试记录和查询。