Appearance
安全与兼容
OPS 兼容传统易支付平台，但不鼓励把历史实现中的不安全行为继续扩大。平台与商户都应在不破坏接入成本的前提下，逐步提升验签、传输、回调和版本治理能力。
安全基线
兼容 OPS 的平台必须满足以下基线：
- 支付请求、查询、通知和配置发现应使用 HTTPS。
.well-known配置不能暴露商户密钥、私钥、管理后台地址或内部令牌。- 商户必须对异步通知验签。
- 商户必须校验订单号、金额、商户号和支付状态。
- 异步通知处理必须幂等。
- 同步返回不能作为最终支付成功依据。
- 平台必须限制订单号长度和字段长度，防止异常请求拖垮服务。
仅本地开发、内网联调或历史平台迁移时可以临时使用 HTTP，但配置中必须声明：
json
{
"security": {
"https_required": false,
"environment": "development"
}
}通知幂等
同一笔订单可能收到多次异步通知。商户实现必须满足：
- 已支付订单再次收到成功通知时，返回
success。 - 已关闭或已退款订单收到成功通知时，不直接覆盖状态，需要进入人工或补偿流程。
- 金额不一致、商户号不一致或订单号不存在时，不能返回
success。 - 数据库更新应使用事务或状态条件更新，避免并发通知导致重复发货。
重放防护
传统易支付 MD5 签名通常不包含时间戳和随机串。为了兼容旧平台，OPS 不强制 OPS-EPAY-1 支持重放防护，但 OPS-EXT-1 应支持：
| 字段 | 说明 |
|---|---|
timestamp | Unix 秒级时间戳或 ISO 8601 时间 |
nonce | 随机字符串 |
key_id | 密钥编号 |
配置示例：
json
{
"security": {
"timestamp_field": "timestamp",
"nonce_field": "nonce",
"max_clock_skew_seconds": 300,
"replay_protection": true
}
}回调地址校验
平台处理 notify_url 和 return_url 时应校验：
- URL 必须是完整绝对地址。
- 生产环境建议只允许 HTTPS。
- 不允许内网地址、回环地址和链路本地地址，除非平台处于开发环境。
- 商户后台可以配置回调域名白名单。
支付方式兼容
不同易支付平台对支付方式命名不完全一致。OPS 使用标准 code 加 aliases 解决兼容问题。
平台应保证：
payment_methods.code稳定，不随展示名称变化。aliases包含平台历史上接受过的旧值。- 禁用的支付方式必须保留条目并标记
enabled=false，不要直接删除导致客户端误判。
字段兼容
平台升级到 OPS 时，建议按以下顺序推进：
- 保留传统字段，例如
pid、type、money。 - 在配置中声明字段别名。
- 增加标准字段支持，例如
merchant_id、payment_method、amount。 - 等接入方完成迁移后，再把标准字段放到别名数组第一位。
旧字段至少保留一个主版本周期。
版本演进
OPS 配置和接口变更分为四类：
| 类型 | 说明 | 兼容要求 |
|---|---|---|
| 新增 | 新增字段、支付方式、接口能力 | 客户端必须忽略未知字段 |
| 变更 | 字段含义、格式、状态值发生变化 | 必须发布迁移说明 |
| 废弃 | 字段或接口不再推荐使用 | 至少保留一个主版本周期 |
| 破坏 | 删除字段、改变签名规则、改变成功判定 | 必须提升主版本号 |
平台不能在不变更版本的情况下修改签名源字符串规则。
错误兼容
传统易支付平台可能返回纯文本错误、HTML 页面或旧格式 JSON。OPS 客户端应按配置处理响应格式，但平台升级时应提供标准 JSON 错误响应。
推荐错误响应：
json
{
"code": 40001,
"message": "invalid signature",
"request_id": "req_202606140930001"
}迁移策略
已有易支付平台接入 OPS 的推荐步骤：
- 先提供
/.well-known/openpayment-configuation，不改变原接口。 - 在配置中完整声明现有提交地址、签名方式、支付方式和字段别名。
- 为通知、查询和错误响应补充标准字段。
- 新增 HMAC-SHA256 或 RSA-SHA256，但继续保留 MD5。
- 对新商户默认推荐更安全的签名方式，对旧商户保持兼容。