配置发现

OPS 平台必须通过固定地址暴露机器可读配置：

txt

GET /.well-known/openpayment-configuation

该接口用于告诉接入方：支付提交到哪里、支持哪些签名方式、有哪些支付方式、字段名如何兼容老易支付平台，以及接口返回格式如何处理。

响应要求

Content-Type 必须为 application/json; charset=utf-8。
响应必须是公开信息，不能包含商户密钥、私钥、后台令牌或任何敏感凭据。
接口应支持 GET，建议支持 HEAD。
HTTP 状态码为 200 时表示配置可用。
建议设置 Cache-Control: public, max-age=300，避免接入方频繁请求。

顶层字段

字段	类型	必填	说明
`spec`	string	是	固定为 `Open Payment Specification`
`spec_version`	string	是	OPS 版本，例如 `1.0.0`
`profile`	string[]	是	平台兼容层级，例如 `OPS-EPAY-1`、`OPS-CORE-1`
`platform`	object	是	平台基本信息
`endpoints`	object	是	接口地址
`signing`	object	是	签名能力
`payment_methods`	object[]	是	支付方式能力
`fields`	object	是	标准字段与易支付字段别名
`amount`	object	否	金额格式
`callbacks`	object	否	通知与返回约定
`compatibility`	object	否	易支付兼容配置

配置示例

json

{
  "spec": "Open Payment Specification",
  "spec_version": "1.0.0",
  "profile": ["OPS-EPAY-1", "OPS-CORE-1"],
  "platform": {
    "name": "Example EPay",
    "vendor": "example",
    "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", "form_post"],
    "refund": [],
    "notify": ["form_post"]
  },
  "signing": {
    "default": "MD5",
    "supported": ["MD5", "HMAC-SHA256", "RSA-SHA256"],
    "sign_field": "sign",
    "sign_type_field": "sign_type",
    "empty_value_policy": "omit",
    "sort": "ascii_asc",
    "charset": "utf-8"
  },
  "payment_methods": [
    {
      "code": "alipay",
      "name": "支付宝",
      "aliases": ["alipay", "ali"],
      "scenes": ["pc", "wap", "qr"],
      "enabled": true
    },
    {
      "code": "wxpay",
      "name": "微信支付",
      "aliases": ["wxpay", "wechat"],
      "scenes": ["pc", "wap", "qr", "jsapi"],
      "enabled": true
    },
    {
      "code": "qqpay",
      "name": "QQ 钱包",
      "aliases": ["qqpay"],
      "scenes": ["pc", "wap", "qr"],
      "enabled": true
    }
  ],
  "fields": {
    "merchant_id": ["pid", "mch_id", "merchant_id"],
    "payment_method": ["type", "payment_method"],
    "merchant_order_no": ["out_trade_no"],
    "subject": ["name", "subject"],
    "amount": ["money", "amount"],
    "notify_url": ["notify_url"],
    "return_url": ["return_url"],
    "client_ip": ["clientip", "client_ip"],
    "metadata": ["param", "metadata"]
  },
  "amount": {
    "currency": "CNY",
    "format": "decimal_string",
    "scale": 2,
    "min": "0.01"
  },
  "callbacks": {
    "notify_success_body": "success",
    "notify_retry": true,
    "return_url_trusted": false
  },
  "compatibility": {
    "epay_sign_type_required": true,
    "query_act_values": ["order", "query"],
    "success_status_values": ["TRADE_SUCCESS", "TRADE_FINISHED", "1"]
  }
}

端点字段

字段	说明
`submit`	面向浏览器跳转或表单提交的支付入口，传统易支付通常为 `/submit.php`
`mapi`	面向接口下单的入口，常见实现为 `/mapi.php`
`api`	通用接口入口，传统易支付常见为 `/api.php`
`query`	订单查询接口，可以是独立地址，也可以是带 `act` 的 `api.php`
`refund`	退款接口，平台不支持时为 `null`
`close`	关闭订单接口，平台不支持时为 `null`

所有端点必须是绝对 URL。平台仅支持相对路径时，配置生成方必须根据当前请求域名转换为绝对 URL。

支付方式字段

payment_methods 中的 code 是 OPS 标准支付方式标识。aliases 用于兼容不同易支付平台使用的旧标识。

标准标识	常见别名	说明
`alipay`	`alipay`、`ali`	支付宝
`wxpay`	`wxpay`、`wechat`	微信支付
`qqpay`	`qqpay`	QQ 钱包
`bank`	`bank`、`unionpay`	网银或银联
`jdpay`	`jdpay`	京东支付
`paypal`	`paypal`	PayPal
`usdt`	`usdt`、`trc20`	USDT 或加密货币通道

平台可以扩展新的支付方式，但必须在配置中声明 code、name、aliases 和 enabled。

字段别名规则

接入方应优先使用平台在 fields 中列出的第一个字段名。例如 merchant_id 的别名为 ["pid", "mch_id", "merchant_id"] 时，默认提交字段应为 pid。

平台如果希望推广 OPS 标准字段，可以把标准字段放在别名数组第一位，同时保留传统字段：

json

{
  "fields": {
    "merchant_id": ["merchant_id", "pid"],
    "amount": ["amount", "money"]
  }
}

版本兼容

spec_version 使用语义化版本。配置新增字段不能破坏旧客户端解析；字段废弃时必须至少保留一个主版本周期。

客户端遇到未知字段必须忽略，不能因为配置中存在新字段而拒绝接入。

配置发现 ​

响应要求 ​

顶层字段 ​

配置示例 ​

端点字段 ​

支付方式字段 ​

字段别名规则 ​

版本兼容 ​