应用后端退回 MetaEco 余额支付

POST /miniapp/v1/apps/{app_id}/payments/orders/{order_id}/refunds

active/draft 应用可办理原订单退款，不依赖前台调试会话仍有效。仅允许当前应用按原平台支付单、业务订单号和稳定业务退款号，从订单固化的原商户资金账户原路退回 Purse 余额；退款成功后异步发送已签名的 REFUND.SUCCESS 事件。可选 notify_url 单独指定本笔退款接收地址，省略时沿用原支付单的 notify_url。订单不存在返回 404，商户余额不足、钱包冻结或账户不可用返回对应 409。结果未明时返回 503 且不得自动发起新退款；服务端以同一操作号查证。同号同参不重复转账；原结果未知的重复 POST 仅查原资金操作，查无仍返回 503。明确拒绝且原操作确认为未发生时，才可在当前有效凭据下以原退款号重新授权。归档、注销暂停或终态拒绝普通退款，原结果仍可由平台核实保存。通知可能重复，业务后端必须验签、去重并查询退款终态。此资金写请求与创建支付单一样始终要求 Bearer token 和有效应用公钥对应的四个签名头。本路径不得有 Query，原始 JSON body 必须与签名时的字节完全一致。

鉴权与参数

使用 Authorization: Bearer <接口 token> 识别应用；每次请求都必须使用应用后端 RSA 私钥生成四个 X-MetaEco-App-* 签名头。缺少签名头或未登记有效支付请求公钥时，请求会被拒绝。私钥只保存在应用后端，签名规范见余额支付签名。

参数	位置	必填	说明
`app_id`	path	是	{"type":"string","pattern":"^[a-z][a-z0-9_-]{2,63}$"}
`order_id`	path	是
`X-MetaEco-App-Key-ID`	header	是	应用后端当前有效签名公钥 ID；与另外三个签名头同时提供。
`X-MetaEco-App-Timestamp`	header	是	签名时的十进制 Unix 秒级时间戳；平台允许前后 5 分钟。与另外三个签名头同组提交。
`X-MetaEco-App-Nonce`	header	是	每次请求由安全随机源生成 16～48 字节并用无填充 Base64URL 编码；重试须重新生成，平台跨实例原子去重至少 15 分钟。与另外三个签名头同组提交。
`X-MetaEco-App-Signature`	header	是	标准 Base64 编码的 RSA PKCS#1 v1.5 + SHA-256 签名；五行签名串依次为大写方法、含 AppID 的去域名 URL 路径、时间戳、nonce、原始 JSON 正文，每行以换行符结尾。与另外三个签名头同组提交。

请求体

Content-Type：application/json。

字段	类型	在所属对象中必填	说明与约束
`business_order_no`	string	是	pattern: ^[0-9A-Za-z_-\|*]+$；minLength: 6；maxLength: 32
`business_refund_no`	string	是	pattern: ^[0-9A-Za-z_-\|*]+$；minLength: 6；maxLength: 32
`amount_minor`	integer	是	minimum: 1；maximum: 1000000000
`reason`	string	是	maxLength: 255
`notify_url`	string	否	description: 可选的本笔退款成功通知地址；须为公网 HTTPS 完整路径，总长不超过 255 个 UTF-8 字节，且无 Query、片段或用户信息。省略时沿用原支付单 notify_url；同号重试不得更改目标。；format: uri；pattern: ^https://[^/@?#]+/[^?#]*$；minLength: 10；maxLength: 255

响应

HTTP 200

成功响应，业务数据位于 data 字段。

字段	类型	在所属对象中必填	说明与约束
`code`	string	是	description: 请求成功时返回的稳定业务码。；const: miniapp_success
`data`	object	是	additionalProperties: true

HTTP 400

请求参数无效。

字段	类型	在所属对象中必填	说明与约束
`error`	object	是
`error.code`	string	是
`error.message`	string	是
`error.request_id`	string	否	description: 与响应头 X-Request-ID 相同，用于查询服务端失败诊断。；maxLength: 128
`error.details`	object	否	additionalProperties: false
`error.details.reason`	string	否

HTTP 401

宿主身份、AppSecret、接口 token 或运行时会话无效。

字段	类型	在所属对象中必填	说明与约束
`error`	object	是
`error.code`	string	是
`error.message`	string	是
`error.request_id`	string	否	description: 与响应头 X-Request-ID 相同，用于查询服务端失败诊断。；maxLength: 128
`error.details`	object	否	additionalProperties: false
`error.details.reason`	string	否

HTTP 404

请求的资源不存在。

字段	类型	在所属对象中必填	说明与约束
`error`	object	是
`error.code`	string	是
`error.message`	string	是
`error.request_id`	string	否	description: 与响应头 X-Request-ID 相同，用于查询服务端失败诊断。；maxLength: 128
`error.details`	object	否	additionalProperties: false
`error.details.reason`	string	否

HTTP 409

状态冲突或幂等键冲突。

字段	类型	在所属对象中必填	说明与约束
`error`	object	是
`error.code`	string	是
`error.message`	string	是
`error.request_id`	string	否	description: 与响应头 X-Request-ID 相同，用于查询服务端失败诊断。；maxLength: 128
`error.details`	object	否	additionalProperties: false
`error.details.reason`	string	否

HTTP 413

请求超过接口大小限制。

字段	类型	在所属对象中必填	说明与约束
`error`	object	是
`error.code`	string	是
`error.message`	string	是
`error.request_id`	string	否	description: 与响应头 X-Request-ID 相同，用于查询服务端失败诊断。；maxLength: 128
`error.details`	object	否	additionalProperties: false
`error.details.reason`	string	否

HTTP 503

依赖的适配器或存储不可用。

字段	类型	在所属对象中必填	说明与约束
`error`	object	是
`error.code`	string	是
`error.message`	string	是
`error.request_id`	string	否	description: 与响应头 X-Request-ID 相同，用于查询服务端失败诊断。；maxLength: 128
`error.details`	object	否	additionalProperties: false
`error.details.reason`	string	否

完整定义

下列定义包含引用、Header 和字段约束，来自同一契约的本接口投影。

查看 JSON Schema 与响应定义

json

{
  "openapi": "3.1.0",
  "info": {
    "title": "MetaEco 应用服务端 API",
    "version": "40.68.0"
  },
  "servers": [
    {
      "url": "{platformOrigin}",
      "description": "导入后填写实际 API 入口；文档域名不承载 API",
      "variables": {
        "platformOrigin": {
          "default": "https://api.example.invalid",
          "description": "替换为当前应用分配的 API 网关，示例域名不可访问"
        }
      }
    }
  ],
  "paths": {
    "/miniapp/v1/apps/{app_id}/payments/orders/{order_id}/refunds": {
      "post": {
        "summary": "应用后端退回 MetaEco 余额支付",
        "description": "active/draft 应用可办理原订单退款，不依赖前台调试会话仍有效。仅允许当前应用按原平台支付单、业务订单号和稳定业务退款号，从订单固化的原商户资金账户原路退回 Purse 余额；退款成功后异步发送已签名的 REFUND.SUCCESS 事件。可选 notify_url 单独指定本笔退款接收地址，省略时沿用原支付单的 notify_url。订单不存在返回 404，商户余额不足、钱包冻结或账户不可用返回对应 409。结果未明时返回 503 且不得自动发起新退款；服务端以同一操作号查证。同号同参不重复转账；原结果未知的重复 POST 仅查原资金操作，查无仍返回 503。明确拒绝且原操作确认为未发生时，才可在当前有效凭据下以原退款号重新授权。归档、注销暂停或终态拒绝普通退款，原结果仍可由平台核实保存。通知可能重复，业务后端必须验签、去重并查询退款终态。此资金写请求与创建支付单一样始终要求 Bearer token 和有效应用公钥对应的四个签名头。本路径不得有 Query，原始 JSON body 必须与签名时的字节完全一致。",
        "tags": [
          "runtime"
        ],
        "security": [
          {
            "interfaceAccessToken": []
          }
        ],
        "operationId": "createMetaEcoPaymentRefund",
        "parameters": [
          {
            "$ref": "#/components/parameters/AppID"
          },
          {
            "$ref": "#/components/parameters/OrderID"
          },
          {
            "$ref": "#/components/parameters/MetaEcoAppKeyID"
          },
          {
            "$ref": "#/components/parameters/MetaEcoAppTimestamp"
          },
          {
            "$ref": "#/components/parameters/MetaEcoAppNonce"
          },
          {
            "$ref": "#/components/parameters/MetaEcoAppSignature"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MetaEcoPaymentRefundRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/ObjectResponse"
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/RuntimeUnauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    }
  },
  "webhooks": {
    "metaEcoBalancePaymentEvent": {
      "post": {
        "summary": "平台向应用后端投递余额支付或退款成功通知",
        "description": "平台向创建支付单时固化的 notify_url 或退款单独指定的 notify_url 发送 HTTPS JSON；同一资金终态对应稳定事件 ID，至少一次投递。接收方必须先使用本应用受信任的 MetaEco 通知公钥验证原始正文，再核对 AppID、业务订单号和金额，并使用应用接口 token 查单确认。成功及已幂等处理的事件应在 5 秒内返回任意 2xx；超时或非 2xx 按退避策略最多尝试 10 次，之后进入死信。重投可有新的时间戳、nonce 和签名，事件正文及 ID 不变。此协议不是微信支付 API v3 通知。",
        "operationId": "receiveMetaEcoBalancePaymentEvent",
        "security": [
          {
            "metaEcoNotificationSignature": []
          }
        ],
        "parameters": [
          {
            "name": "X-MetaEco-Event-ID",
            "in": "header",
            "required": true,
            "description": "必须与正文 id 相同，跨重试不变。",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-MetaEco-Key-ID",
            "in": "header",
            "required": true,
            "description": "选择验签公钥，并作为签名串第一行。",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-MetaEco-Timestamp",
            "in": "header",
            "required": true,
            "description": "当前投递生成的十进制 Unix 秒；接收方允许的时钟偏差为前后 5 分钟。",
            "schema": {
              "type": "string",
              "pattern": "^[0-9]+$"
            }
          },
          {
            "name": "X-MetaEco-Nonce",
            "in": "header",
            "required": true,
            "description": "当前投递生成的随机字符串。",
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 64
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/MetaEcoPaymentSucceededEvent"
                  },
                  {
                    "$ref": "#/components/schemas/MetaEcoRefundSucceededEvent"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "验签并持久化处理或已幂等处理；任何 2xx 均表示确认接收。"
          },
          "204": {
            "description": "验签并持久化处理或已幂等处理；没有响应正文。"
          },
          "400": {
            "description": "通知字段、身份或金额校验失败；平台会重试至死信。"
          },
          "401": {
            "description": "签名、公钥 ID 或时间窗校验失败；平台会重试至死信。"
          },
          "503": {
            "description": "接收方暂时不可用；平台会重试至死信。"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "interfaceAccessToken": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "MiniAppInterfaceAccessToken",
        "description": "应用后端用 AppSecret 换取的 2 小时接口 token；仅用于应用后端接口，禁止交给宿主或小程序。"
      },
      "metaEcoNotificationSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "X-MetaEco-Signature",
        "description": "Base64 编码的 RSA PKCS#1 v1.5 + SHA-256 签名；签名串为 X-MetaEco-Key-ID、X-MetaEco-Timestamp、X-MetaEco-Nonce、原始 UTF-8 正文逐行连接且正文后再加换行。"
      }
    },
    "parameters": {
      "AppID": {
        "name": "app_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "pattern": "^[a-z][a-z0-9_-]{2,63}$"
        }
      },
      "OrderID": {
        "name": "order_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        }
      },
      "MetaEcoAppKeyID": {
        "name": "X-MetaEco-App-Key-ID",
        "in": "header",
        "required": true,
        "description": "应用后端当前有效签名公钥 ID；与另外三个签名头同时提供。",
        "schema": {
          "type": "string",
          "pattern": "^[0-9a-f]{32}$"
        }
      },
      "MetaEcoAppTimestamp": {
        "name": "X-MetaEco-App-Timestamp",
        "in": "header",
        "required": true,
        "description": "签名时的十进制 Unix 秒级时间戳；平台允许前后 5 分钟。与另外三个签名头同组提交。",
        "schema": {
          "type": "string",
          "pattern": "^[0-9]{10,11}$"
        }
      },
      "MetaEcoAppNonce": {
        "name": "X-MetaEco-App-Nonce",
        "in": "header",
        "required": true,
        "description": "每次请求由安全随机源生成 16～48 字节并用无填充 Base64URL 编码；重试须重新生成，平台跨实例原子去重至少 15 分钟。与另外三个签名头同组提交。",
        "schema": {
          "type": "string",
          "minLength": 22,
          "maxLength": 64,
          "pattern": "^[A-Za-z0-9_-]+$"
        }
      },
      "MetaEcoAppSignature": {
        "name": "X-MetaEco-App-Signature",
        "in": "header",
        "required": true,
        "description": "标准 Base64 编码的 RSA PKCS#1 v1.5 + SHA-256 签名；五行签名串依次为大写方法、含 AppID 的去域名 URL 路径、时间戳、nonce、原始 JSON 正文，每行以换行符结尾。与另外三个签名头同组提交。",
        "schema": {
          "type": "string",
          "minLength": 128,
          "maxLength": 1024
        }
      }
    },
    "schemas": {
      "MetaEcoPaymentRefundRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "business_order_no",
          "business_refund_no",
          "amount_minor",
          "reason"
        ],
        "properties": {
          "business_order_no": {
            "type": "string",
            "minLength": 6,
            "maxLength": 32,
            "pattern": "^[0-9A-Za-z_\\-|*]+$"
          },
          "business_refund_no": {
            "type": "string",
            "minLength": 6,
            "maxLength": 32,
            "pattern": "^[0-9A-Za-z_\\-|*]+$"
          },
          "amount_minor": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000000000
          },
          "reason": {
            "type": "string",
            "maxLength": 255
          },
          "notify_url": {
            "type": "string",
            "format": "uri",
            "minLength": 10,
            "maxLength": 255,
            "pattern": "^https://[^/@?#]+/[^?#]*$",
            "description": "可选的本笔退款成功通知地址；须为公网 HTTPS 完整路径，总长不超过 255 个 UTF-8 字节，且无 Query、片段或用户信息。省略时沿用原支付单 notify_url；同号重试不得更改目标。"
          }
        }
      },
      "ObjectResponse": {
        "type": "object",
        "required": [
          "code",
          "data"
        ],
        "properties": {
          "code": {
            "$ref": "#/components/schemas/SuccessCode"
          },
          "data": {
            "$ref": "#/components/schemas/GenericObject"
          }
        }
      },
      "SuccessCode": {
        "type": "string",
        "const": "miniapp_success",
        "description": "请求成功时返回的稳定业务码。"
      },
      "GenericObject": {
        "type": "object",
        "additionalProperties": true
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "request_id": {
                "type": "string",
                "maxLength": 128,
                "description": "与响应头 X-Request-ID 相同，用于查询服务端失败诊断。"
              },
              "details": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "reason": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "MetaEcoPaymentSucceededEvent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "create_time",
          "event_type",
          "resource"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "稳定事件 ID，重复投递时不变。"
          },
          "create_time": {
            "type": "string",
            "format": "date-time"
          },
          "event_type": {
            "type": "string",
            "const": "TRANSACTION.SUCCESS"
          },
          "resource": {
            "$ref": "#/components/schemas/MetaEcoPaymentSucceededResource"
          }
        }
      },
      "MetaEcoPaymentSucceededResource": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "app_id",
          "order_id",
          "business_type",
          "business_order_no",
          "transaction_id",
          "amount_minor",
          "currency",
          "paid_at",
          "status"
        ],
        "properties": {
          "app_id": {
            "type": "string"
          },
          "order_id": {
            "type": "string",
            "format": "uuid"
          },
          "business_type": {
            "type": "string",
            "enum": [
              "trade",
              "shop"
            ]
          },
          "business_order_no": {
            "type": "string"
          },
          "transaction_id": {
            "type": "string"
          },
          "amount_minor": {
            "type": "integer",
            "minimum": 1
          },
          "currency": {
            "type": "string",
            "const": "CNY"
          },
          "paid_at": {
            "type": "string",
            "format": "date-time"
          },
          "status": {
            "type": "string",
            "const": "paid"
          }
        }
      },
      "MetaEcoRefundSucceededEvent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "create_time",
          "event_type",
          "resource"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "稳定事件 ID，重复投递时不变。"
          },
          "create_time": {
            "type": "string",
            "format": "date-time"
          },
          "event_type": {
            "type": "string",
            "const": "REFUND.SUCCESS"
          },
          "resource": {
            "$ref": "#/components/schemas/MetaEcoRefundSucceededResource"
          }
        }
      },
      "MetaEcoRefundSucceededResource": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "app_id",
          "order_id",
          "business_type",
          "business_order_no",
          "transaction_id",
          "amount_minor",
          "currency",
          "paid_at",
          "refund_id",
          "business_refund_no",
          "refund_amount_minor",
          "refunded_at",
          "status"
        ],
        "properties": {
          "app_id": {
            "type": "string"
          },
          "order_id": {
            "type": "string",
            "format": "uuid"
          },
          "business_type": {
            "type": "string",
            "enum": [
              "trade",
              "shop"
            ]
          },
          "business_order_no": {
            "type": "string"
          },
          "transaction_id": {
            "type": "string"
          },
          "amount_minor": {
            "type": "integer",
            "minimum": 1
          },
          "currency": {
            "type": "string",
            "const": "CNY"
          },
          "paid_at": {
            "type": "string",
            "format": "date-time"
          },
          "refund_id": {
            "type": "string",
            "format": "uuid"
          },
          "business_refund_no": {
            "type": "string"
          },
          "refund_amount_minor": {
            "type": "integer",
            "minimum": 1
          },
          "refunded_at": {
            "type": "string",
            "format": "date-time"
          },
          "status": {
            "type": "string",
            "const": "refunded"
          }
        }
      }
    },
    "responses": {
      "ObjectResponse": {
        "description": "成功响应，业务数据位于 data 字段。",
        "headers": {
          "X-Request-ID": {
            "$ref": "#/components/headers/RequestID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ObjectResponse"
            }
          }
        }
      },
      "InvalidRequest": {
        "description": "请求参数无效。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "RuntimeUnauthorized": {
        "description": "宿主身份、AppSecret、接口 token 或运行时会话无效。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "NotFound": {
        "description": "请求的资源不存在。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Conflict": {
        "description": "状态冲突或幂等键冲突。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "PayloadTooLarge": {
        "description": "请求超过接口大小限制。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "依赖的适配器或存储不可用。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "headers": {
      "RequestID": {
        "description": "请求追踪 ID，用于关联客户端、网关和服务端日志。",
        "schema": {
          "type": "string",
          "maxLength": 128
        }
      }
    }
  }
}

返回 API 目录

应用后端退回 MetaEco 余额支付 ​

鉴权与参数 ​

请求体 ​

响应 ​

HTTP 200 ​

HTTP 400 ​

HTTP 401 ​

HTTP 404 ​

HTTP 409 ​

HTTP 413 ​

HTTP 503 ​

完整定义 ​