{
  "openapi": "3.0.3",
  "info": {
    "title": "商户支付接入API",
    "description": "pay-webman 支付系统对外接口文档\n\n## 概述\n\n本系统提供支付（代收）和代付（提现）两大类 API 接口，采用表单格式通信。\n\n## 签名算法\n\n- **表单 API 签名**：MD5 小写，固定顺序，`&{apikey}` 拼接\n- **代付表单 API 签名**：MD5 小写，ksort 排序，`key={apikey}` 拼接\n\n## 金额单位\n\n- 表单 API：元（支持小数）",
    "version": "1.0.0",
    "contact": {
      "name": "技术支持",
      "url": "/apidoc"
    }
  },
  "servers": [],
  "tags": [
    {
      "name": "支付API-表单",
      "description": "表单格式支付（代收）接口，签名算法为 MD5 小写固定顺序"
    },
    {
      "name": "代付API-表单",
      "description": "表单格式代付（提现）接口，签名算法为 MD5 小写 ksort"
    },
    {
      "name": "异步通知",
      "description": "支付成功后平台主动推送到商户的通知接口"
    }
  ],
  "paths": {
    "/apisubmit": {
      "post": {
        "tags": ["支付API-表单"],
        "summary": "表单支付下单",
        "description": "通过表单提交支付订单。金额单位为元（支持小数）。\n\n**签名算法**：表单 API 签名（MD5 小写，固定顺序）\n\n**签名串格式**：`version=1.0&customerid=10000&total_fee=100.00&sdorderno=...&notifyurl=...&returnurl=...&{apikey}`\n\n**响应规则**：\n- 带 `cardnum` 参数：返回 JSON `{\"code\":200,\"payurl\":\"...\"}`\n- 不带 `cardnum` 参数：返回纯文本支付链接",
        "operationId": "apiSubmit",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/FormPayRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功响应（JSON 或纯文本）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FormPayJsonResponse"
                },
                "examples": {
                  "成功（带cardnum）": {
                    "value": "{\"code\": 200, \"payurl\": \"https://openapi.alipay.com/gateway.do?...\"}"
                  },
                  "失败": {
                    "value": "{\"code\": 205, \"msg\": \"订单号已存在\"}"
                  }
                }
              },
              "text/plain": {
                "examples": {
                  "成功（不带cardnum）": {
                    "value": "https://openapi.alipay.com/gateway.do?..."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/app/pay/query/order": {
      "post": {
        "tags": ["支付API-表单"],
        "summary": "表单订单查询",
        "description": "通过表单查询支付订单状态。\n\n**签名算法**：表单 API 签名（MD5 小写，固定顺序）",
        "operationId": "formPayQuery",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/FormPayQueryRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功响应",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FormPayQueryResponse"
                },
                "examples": {
                  "成功": {
                    "value": "{\"code\": 200, \"orderid\": \"ORDER202606170001\", \"total_fee\": \"100.00\", \"pay_status\": \"1\", \"addtime\": \"1718600000\"}"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/apidai": {
      "post": {
        "tags": ["代付API-表单"],
        "summary": "表单代付下单",
        "description": "通过表单提交代付（提现）订单。金额单位为元（支持小数）。\n\n**签名算法**：代付表单 API 签名（MD5 小写，ksort）\n\n**签名串格式**：`customerid=10000&dai_no=...&total_money=100.00&version=1.0&key={apikey}`（ksort 排序后拼接，每个参数后带 `&`）",
        "operationId": "apiDai",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/FormCashPaymentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功响应",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FormCashPaymentResponse"
                },
                "examples": {
                  "成功": {
                    "value": "{\"customerid\": \"10000\", \"dai_no\": \"DEPOSIT202606170001\", \"serialno_state\": \"SUCCESS\", \"charge\": \"0.00\", \"account\": \"advance\", \"total_money\": \"100.00\", \"tfb_rsptime\": \"1718600000\", \"sign\": \"a1b2c3d4e5f67890abcdef1234567890\"}"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/apidai/api_query": {
      "post": {
        "tags": ["代付API-表单"],
        "summary": "表单代付查询",
        "description": "通过表单查询代付订单状态。\n\n**签名算法**：代付表单 API 签名（MD5 小写，ksort）",
        "operationId": "apiDaiQuery",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/FormCashQueryRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功响应",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FormCashPaymentResponse"
                },
                "examples": {
                  "成功": {
                    "value": "{\"customerid\": \"10000\", \"dai_no\": \"DEPOSIT202606170001\", \"serialno_state\": \"SUCCESS\", \"charge\": \"0.00\", \"total_money\": \"100.00\", \"tfb_rsptime\": \"1718600000\", \"sign\": \"a1b2c3d4e5f67890abcdef1234567890\"}"
                  },
                  "失败": {
                    "value": "{\"retcode\": \"ORDERNOTEXIST\", \"retmsg\": \"此代付订单不存在\"}"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/apidai/balance_query": {
      "post": {
        "tags": ["代付API-表单"],
        "summary": "表单余额查询",
        "description": "通过表单查询商户可用余额。\n\n**签名算法**：代付表单 API 签名（MD5 小写，ksort）",
        "operationId": "apiDaiBalance",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/FormCashBalanceRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功响应",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FormCashBalanceResponse"
                },
                "examples": {
                  "成功": {
                    "value": "{\"customerid\": \"10000\", \"retcode\": \"PASS\", \"retmsg\": \"查询成功\", \"advance\": \"10000.00\", \"fund\": \"0\", \"freeze\": \"0\", \"sign\": \"a1b2c3d4e5f67890abcdef1234567890\"}"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/notify/callback": {
      "post": {
        "tags": ["异步通知"],
        "summary": "支付成功异步通知（商户接收）",
        "description": "支付成功后，平台主动 POST 推送到商户配置的 notify_url。\n\n**推送方式**：HTTP POST，Content-Type: application/json\n\n**商户响应要求**：返回 `success`（不区分大小写），HTTP 200\n\n**重试机制**：最多 6 次，间隔 30/60/120/240/480/960 秒\n\n**验签**：使用 通知签名算法（MD5 小写）验证 sign 字段",
        "operationId": "notifyCallback",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NotifyRequest"
              },
              "examples": {
                "通知报文": {
                  "value": "{\n  \"customerid\": \"10000\",\n  \"orderid\": \"ORDER202606170001\",\n  \"total_fee\": \"10000\",\n  \"pay_status\": \"1\",\n  \"time\": \"1718600000\",\n  \"nonce_str\": \"a1b2c3d4e5f6\",\n  \"sign\": \"A1B2C3D4E5F678901234567890ABCDEF\"\n}"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "商户需返回 success 字样",
            "content": {
              "text/plain": {
                "examples": {
                  "正确响应": {
                    "value": "success"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "FormPayRequest": {
        "type": "object",
        "title": "表单支付下单请求",
        "properties": {
          "customerid": { "type": "integer", "description": "商户ID", "example": 10000 },
          "total_fee": { "type": "number", "description": "订单金额（单位：元，支持小数）", "example": 100.00 },
          "sdorderno": { "type": "string", "description": "商户订单号", "example": "ORDER202606170001" },
          "notifyurl": { "type": "string", "description": "异步通知地址", "example": "http://example.com/notify" },
          "returnurl": { "type": "string", "description": "同步跳转地址", "example": "http://example.com/return" },
          "paytype": { "type": "string", "description": "支付类型（Alipay/Weixin/Bank 等）", "example": "Alipay" },
          "sign": { "type": "string", "description": "签名值（MD5 小写）" },
          "version": { "type": "string", "description": "版本号（默认 1.0）", "example": "1.0", "default": "1.0" },
          "bankcode": { "type": "string", "description": "银行代码（paytype=Bank 时必填）" },
          "remark": { "type": "string", "description": "备注" },
          "cardnum": { "type": "string", "description": "卡号（存在时返回 JSON，否则返回纯文本 URL）" }
        },
        "required": ["customerid", "total_fee", "sdorderno", "notifyurl", "returnurl", "paytype", "sign"]
      },
      "FormPayJsonResponse": {
        "type": "object",
        "title": "表单支付下单响应（JSON）",
        "properties": {
          "code": { "type": "integer", "description": "200 表示成功，其他为错误码" },
          "payurl": { "type": "string", "description": "支付链接（成功时返回）" },
          "msg": { "type": "string", "description": "错误信息（失败时返回）" }
        }
      },
      "FormPayQueryRequest": {
        "type": "object",
        "title": "表单订单查询请求",
        "properties": {
          "customerid": { "type": "integer", "description": "商户ID", "example": 10000 },
          "sdorderno": { "type": "string", "description": "商户订单号（与 orderid 二选一）", "example": "ORDER202606170001" },
          "orderid": { "type": "string", "description": "商户订单号（与 sdorderno 二选一）" },
          "sign": { "type": "string", "description": "签名值（MD5 小写）" }
        },
        "required": ["customerid", "sign"]
      },
      "FormPayQueryResponse": {
        "type": "object",
        "title": "表单订单查询响应",
        "properties": {
          "code": { "type": "integer", "description": "200 表示成功" },
          "orderid": { "type": "string", "description": "商户订单号" },
          "total_fee": { "type": "string", "description": "订单金额（单位：元）" },
          "pay_status": { "type": "string", "description": "支付状态：0=未支付, 1=已支付" },
          "addtime": { "type": "string", "description": "下单时间戳" }
        }
      },
      "FormCashPaymentRequest": {
        "type": "object",
        "title": "表单代付下单请求",
        "properties": {
          "customerid": { "type": "integer", "description": "商户ID", "example": 10000 },
          "version": { "type": "string", "description": "版本号", "example": "1.0" },
          "dai_no": { "type": "string", "description": "代付订单号", "example": "DEPOSIT202606170001" },
          "total_money": { "type": "number", "description": "代付金额（单位：元）", "example": 100.00 },
          "recv_accno": { "type": "string", "description": "收款账号", "example": "6222021234567890123" },
          "acct_name": { "type": "string", "description": "收款人姓名", "example": "张三" },
          "cnaps_name": { "type": "string", "description": "联行号/支行名称", "example": "工行北京分行营业部" },
          "recv_province": { "type": "string", "description": "省份", "example": "北京" },
          "recv_city": { "type": "string", "description": "城市", "example": "北京市" },
          "code": { "type": "string", "description": "代付通道代码", "example": "abc" },
          "sign": { "type": "string", "description": "签名值（MD5 小写）" }
        },
        "required": ["customerid", "version", "dai_no", "total_money", "recv_accno", "acct_name", "cnaps_name", "recv_province", "recv_city", "code", "sign"]
      },
      "FormCashPaymentResponse": {
        "type": "object",
        "title": "表单代付响应",
        "properties": {
          "customerid": { "type": "string", "description": "商户ID" },
          "dai_no": { "type": "string", "description": "代付订单号" },
          "serialno_state": { "type": "string", "description": "代付状态：SUCCESS=成功, FAIL=失败, PEND=处理中" },
          "charge": { "type": "string", "description": "手续费（单位：元）" },
          "account": { "type": "string", "description": "扣款账户（advance=可用余额）" },
          "total_money": { "type": "string", "description": "代付金额（单位：元）" },
          "tfb_rsptime": { "type": "string", "description": "响应时间戳" },
          "sign": { "type": "string", "description": "响应签名（MD5 小写）" }
        }
      },
      "FormCashQueryRequest": {
        "type": "object",
        "title": "表单代付查询请求",
        "properties": {
          "customerid": { "type": "integer", "description": "商户ID", "example": 10000 },
          "dai_no": { "type": "string", "description": "代付订单号", "example": "DEPOSIT202606170001" },
          "aisle": { "type": "string", "description": "通道标识", "example": "abc" },
          "sign": { "type": "string", "description": "签名值（MD5 小写）" }
        },
        "required": ["customerid", "dai_no", "aisle", "sign"]
      },
      "FormCashBalanceRequest": {
        "type": "object",
        "title": "表单余额查询请求",
        "properties": {
          "customerid": { "type": "integer", "description": "商户ID", "example": 10000 },
          "aisle": { "type": "string", "description": "通道标识", "example": "abc" },
          "sign": { "type": "string", "description": "签名值（MD5 小写）" }
        },
        "required": ["customerid", "aisle", "sign"]
      },
      "FormCashBalanceResponse": {
        "type": "object",
        "title": "表单余额查询响应",
        "properties": {
          "customerid": { "type": "string", "description": "商户ID" },
          "retcode": { "type": "string", "description": "PASS=成功, FAIL=失败" },
          "retmsg": { "type": "string", "description": "响应信息" },
          "advance": { "type": "string", "description": "可用余额（单位：元）" },
          "fund": { "type": "string", "description": "资金（通常为 0）" },
          "freeze": { "type": "string", "description": "冻结金额（单位：元）" },
          "sign": { "type": "string", "description": "响应签名" }
        }
      },
      "NotifyRequest": {
        "type": "object",
        "title": "异步通知报文",
        "description": "平台推送到商户 notify_url 的支付结果通知",
        "properties": {
          "customerid": { "type": "integer", "description": "商户ID" },
          "orderid": { "type": "string", "description": "商户订单号" },
          "total_fee": { "type": "integer", "description": "订单金额（单位：分）" },
          "pay_status": { "type": "integer", "description": "支付状态：1=已支付" },
          "time": { "type": "integer", "description": "时间戳" },
          "nonce_str": { "type": "string", "description": "随机字符串" },
          "sign": { "type": "string", "description": "通知签名（通知签名算法，MD5 小写）" }
        }
      }
    }
  }
}