{"openapi":"3.1.0","info":{"title":"Pay 商户支付接口","version":"1.0.0","description":"仅三个商户方法。HTTPS + 商户独立 Bearer 密钥。浏览器回跳不是履约依据，业务端必须使用查询接口确认 PAID。业务应用 ID 与支付宝 AppID 独立。 无商户支付通知接口；未回跳付款需通过查询补偿。"},"servers":[{"url":"https://pay.appsvc.net"}],"security":[{"merchantId":[],"merchantKey":[]}],"tags":[{"name":"Payments","description":"公共商户支付服务"}],"paths":{"/v1/payments":{"post":{"operationId":"createPayment","tags":["Payments"],"summary":"发起支付","description":"merchant_id + business_order_no 幂等。同号金额、标题、回跳地址必须一致。订单冻结账户，后续配置变化不影响历史订单。","responses":{"200":{"description":"请求已处理","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedPayment"}}}},"400":{"description":"参数无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"商户密钥错误或商户禁用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"订单不存在或不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"幂等冲突或退款额度不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"请求过于频繁","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"服务暂时不可用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"支付宝结果暂时无法确认","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePayment"}}}}}},"/v1/payments/{paymentId}":{"parameters":[{"name":"paymentId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$"}}],"get":{"operationId":"getPayment","tags":["Payments"],"summary":"查询支付结果","description":"使用订单原支付宝账户查询并核对可信结果。只有 status=PAID 才可履约；trade_no 为已核对支付宝交易号。付款事实保留，退款结果通过原退款请求幂等重试确认。","responses":{"200":{"description":"请求已处理","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"400":{"description":"参数无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"商户密钥错误或商户禁用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"订单不存在或不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"幂等冲突或退款额度不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"请求过于频繁","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"服务暂时不可用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"支付宝结果暂时无法确认","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/payments/{paymentId}/refunds":{"parameters":[{"name":"paymentId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$"}}],"post":{"operationId":"refundPayment","tags":["Payments"],"summary":"退款","description":"request_no 在订单内幂等。相同请求再次提交即复用原支付宝退款号确认结果。网络结果不确定返回 PENDING 并占用额度。","responses":{"200":{"description":"请求已处理","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refund"}}}},"400":{"description":"参数无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"商户密钥错误或商户禁用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"订单不存在或不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"幂等冲突或退款额度不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"请求过于频繁","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"服务暂时不可用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"支付宝结果暂时无法确认","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundRequest"}}}}}}},"components":{"securitySchemes":{"merchantId":{"type":"apiKey","in":"header","name":"X-Merchant-Id"},"merchantKey":{"type":"http","scheme":"bearer","description":"后台为当前商户创建的独立 API 密钥，仅服务端保存"}},"schemas":{"CreatePayment":{"type":"object","required":["business_order_no","amount","subject"],"properties":{"business_order_no":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,80}$"},"amount":{"type":"string","pattern":"^\\d{1,9}(\\.\\d{1,2})?$","description":"人民币元字符串，范围 0.01–100000000.00；不接受浮点数或科学计数法","examples":["18.00"]},"subject":{"type":"string","minLength":1,"maxLength":128},"return_url":{"type":"string","maxLength":2048,"description":"可选 HTTPS 回跳地址，必须匹配商户允许 origin。确认 PAID 后展示成功页并在 3 秒后回跳，提供立即返回按钮，附加 out_trade_no（business_order_no）与 payment_id，不附加 trade_no。原 URL 的其他参数保留，同名参数覆盖。省略或空字符串停留 pay 结果页。浏览器回跳不是付款依据，商户必须服务端查询并幂等履约。"}}},"Payment":{"type":"object","required":["payment_id","merchant_id","business_order_no","amount","status","trade_no","expires_at"],"properties":{"payment_id":{"type":"string","description":"pay 生成的支付单号；新格式为北京时间日期时间、商户前缀及随机后缀，历史格式继续有效"},"merchant_id":{"type":"string"},"business_order_no":{"type":"string"},"amount":{"type":"string","pattern":"^\\d{1,9}(\\.\\d{1,2})?$","description":"人民币元字符串，范围 0.01–100000000.00；不接受浮点数或科学计数法","examples":["18.00"]},"status":{"type":"string","enum":["WAIT_BUYER_PAY","PAID","TRADE_CLOSED"]},"trade_no":{"type":"string"},"expires_at":{"type":"string","format":"date-time","description":"UTC 付款截止时间，pay 创建时起 30 分钟。重复请求不延期；过期不阻止结果查询或退款。"}}},"CreatedPayment":{"allOf":[{"$ref":"#/components/schemas/Payment"},{"type":"object","required":["checkout_url"],"properties":{"checkout_url":{"type":"string","format":"uri","description":"浏览器跳转至此公网收银 URL；属于能力凭证，勿记录或分享。"}}}]},"RefundRequest":{"type":"object","required":["request_no","amount"],"properties":{"request_no":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,80}$"},"amount":{"type":"string","pattern":"^\\d{1,9}(\\.\\d{1,2})?$","description":"人民币元字符串，范围 0.01–100000000.00；不接受浮点数或科学计数法","examples":["18.00"]},"reason":{"type":"string","maxLength":256}}},"Refund":{"type":"object","required":["payment_id","request_no","amount","status"],"properties":{"payment_id":{"type":"string"},"request_no":{"type":"string"},"amount":{"type":"string","pattern":"^\\d{1,9}(\\.\\d{1,2})?$","description":"人民币元字符串，范围 0.01–100000000.00；不接受浮点数或科学计数法","examples":["18.00"]},"status":{"type":"string","enum":["PENDING","SUCCEEDED"],"description":"PENDING 为未确认，仍占用额度。使用相同退款号、金额和原因重试，不得换号。"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}