{"openapi":"3.1.0","info":{"title":"NovaPay API","version":"0.1.0","description":"NovaPay 支付网关 API，覆盖商户下单、商户自有通道实例、支付回调和后台配置接口。"},"servers":[{"url":"https://pay.muyuai.top","description":"当前 NovaPay 环境"}],"tags":[{"name":"Health","description":"服务健康检查与通道发现"},{"name":"Payments","description":"商户侧支付与退款接口"},{"name":"Callbacks","description":"上游支付平台回调接口"},{"name":"Admin","description":"仅后台管理员可用的配置接口"}],"components":{"securitySchemes":{"AdminSessionCookie":{"type":"apiKey","in":"cookie","name":"novapay_admin_session","description":"NovaPay 后台签发的管理员会话 Cookie"}},"schemas":{"Merchant":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED","SUSPENDED"]},"legalName":{"type":["string","null"]},"contactName":{"type":["string","null"]},"contactEmail":{"type":["string","null"]},"contactPhone":{"type":["string","null"]},"companyRegistrationId":{"type":["string","null"]},"onboardingNote":{"type":["string","null"]},"reviewNote":{"type":["string","null"]},"approvedAt":{"type":["string","null"],"format":"date-time"},"approvedBy":{"type":["string","null"]},"statusChangedAt":{"type":["string","null"],"format":"date-time"},"callbackBase":{"type":["string","null"],"format":"uri","description":"订单未单独传 callbackUrl 时，NovaPay 使用的默认商户业务回调地址。"},"notifySecret":{"type":["string","null"]},"apiIpWhitelist":{"type":["string","null"]},"callbackEnabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"MerchantChannelAccount":{"type":"object","properties":{"id":{"type":"string"},"merchantId":{"type":"string"},"providerKey":{"type":"string"},"channelCode":{"type":"string"},"displayName":{"type":"string"},"config":{"type":"object","additionalProperties":true},"callbackToken":{"type":"string"},"enabled":{"type":"boolean"},"remark":{"type":["string","null"]},"lastVerifiedAt":{"type":["string","null"],"format":"date-time"},"lastErrorMessage":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"MerchantChannelBinding":{"type":"object","properties":{"id":{"type":"string"},"merchantCode":{"type":"string"},"channelCode":{"type":"string"},"enabled":{"type":"boolean"},"merchantChannelAccountId":{"type":["string","null"]},"minAmount":{"type":["string","null"]},"maxAmount":{"type":["string","null"]},"feeRate":{"type":["string","null"]}}},"CreateOrderRequest":{"type":"object","required":["merchantCode","channelCode","externalOrderId","amount","subject"],"properties":{"merchantCode":{"type":"string"},"channelCode":{"type":"string","enum":["alipay.page","wxpay.native"]},"externalOrderId":{"type":"string"},"amount":{"oneOf":[{"type":"string"},{"type":"number"}]},"currency":{"type":"string","enum":["CNY"]},"subject":{"type":"string"},"description":{"type":["string","null"]},"returnUrl":{"type":["string","null"],"format":"uri","description":"支付完成后的可选浏览器返回地址；不传时，NovaPay 使用托管结果页。"},"callbackUrl":{"type":["string","null"],"format":"uri","description":"当前订单的可选商户业务回调地址；不传时，NovaPay 使用商户默认 callbackBase。"},"metadata":{"type":"object","additionalProperties":true}}},"QueryOrderRequest":{"type":"object","required":["merchantCode"],"properties":{"merchantCode":{"type":"string"},"orderReference":{"type":["string","null"]},"orderId":{"type":["string","null"]},"externalOrderId":{"type":["string","null"]},"sync":{"type":"boolean"}}},"CloseOrderRequest":{"type":"object","required":["merchantCode"],"properties":{"merchantCode":{"type":"string"},"orderReference":{"type":["string","null"]},"orderId":{"type":["string","null"]},"externalOrderId":{"type":["string","null"]}}},"QueryOrderByPathRequest":{"type":"object","required":["merchantCode"],"properties":{"merchantCode":{"type":"string"},"sync":{"type":"boolean"}}},"CloseOrderByPathRequest":{"type":"object","required":["merchantCode"],"properties":{"merchantCode":{"type":"string"}}},"PaymentOrderResponse":{"type":"object","properties":{"created":{"type":"boolean"},"order":{"type":"object","properties":{"id":{"type":"string"},"merchantCode":{"type":"string"},"externalOrderId":{"type":"string"},"channelCode":{"type":"string"},"amount":{"type":"string"},"feeRate":{"type":"string"},"feeAmount":{"type":"string"},"netAmount":{"type":"string"},"currency":{"type":"string"},"subject":{"type":["string","null"]},"description":{"type":["string","null"]},"status":{"type":"string"},"providerStatus":{"type":["string","null"]},"gatewayOrderId":{"type":["string","null"]},"checkoutUrl":{"type":["string","null"]},"hostedCheckoutUrl":{"type":["string","null"],"format":"uri"},"paymentMode":{"type":["string","null"],"enum":["redirect","qr_code",null]},"callbackStatus":{"type":"string"},"merchantChannelAccountId":{"type":["string","null"]},"channelAccountSource":{"type":["string","null"],"enum":["merchant",null]},"providerPayload":{"type":["object","null"],"additionalProperties":true},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"expireAt":{"type":["string","null"],"format":"date-time"},"paidAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"refundSummary":{"type":["object","null"],"properties":{"totalRequestedAmount":{"type":"string"},"totalRefundedAmount":{"type":"string"},"refundableAmount":{"type":"string"}}}}}}},"CreateRefundRequest":{"type":"object","required":["merchantCode","externalRefundId","amount"],"properties":{"merchantCode":{"type":"string"},"orderReference":{"type":["string","null"]},"orderId":{"type":["string","null"]},"externalOrderId":{"type":["string","null"]},"externalRefundId":{"type":"string"},"amount":{"oneOf":[{"type":"string"},{"type":"number"}]},"reason":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":true}}},"QueryRefundRequest":{"type":"object","required":["merchantCode"],"properties":{"merchantCode":{"type":"string"},"refundReference":{"type":["string","null"]},"refundId":{"type":["string","null"]},"externalRefundId":{"type":["string","null"]},"sync":{"type":"boolean"}}},"CreateRefundForOrderRequest":{"type":"object","required":["merchantCode","externalRefundId","amount"],"properties":{"merchantCode":{"type":"string"},"externalRefundId":{"type":"string"},"amount":{"oneOf":[{"type":"string"},{"type":"number"}]},"reason":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":true}}},"QueryRefundByPathRequest":{"type":"object","required":["merchantCode"],"properties":{"merchantCode":{"type":"string"},"sync":{"type":"boolean"}}},"PaymentRefundResponse":{"type":"object","properties":{"created":{"type":"boolean"},"refund":{"type":"object","properties":{"id":{"type":"string"},"merchantCode":{"type":"string"},"paymentOrderId":{"type":"string"},"externalOrderId":{"type":"string"},"channelCode":{"type":"string"},"externalRefundId":{"type":"string"},"amount":{"type":"string"},"feeAmount":{"type":"string"},"netAmountImpact":{"type":"string"},"currency":{"type":"string"},"status":{"type":"string"},"providerStatus":{"type":["string","null"]},"providerRefundId":{"type":["string","null"]},"gatewayOrderId":{"type":["string","null"]},"merchantChannelAccountId":{"type":["string","null"]},"channelAccountSource":{"type":["string","null"],"enum":["merchant",null]},"reason":{"type":["string","null"]},"failureCode":{"type":["string","null"]},"failureMessage":{"type":["string","null"]},"metadata":{"type":["object","null"],"additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"refundedAt":{"type":["string","null"],"format":"date-time"}}}}},"SystemConfigItem":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"},"group":{"type":"string"},"label":{"type":["string","null"]},"updatedAt":{"type":"string","format":"date-time"}}}}},"paths":{"/api/health":{"get":{"tags":["Health"],"summary":"健康检查","responses":{"200":{"description":"服务与数据库状态","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"database":{"type":"string"}}}}}}}}},"/api/channels":{"get":{"tags":["Health"],"summary":"列出支付通道","responses":{"200":{"description":"可用支付通道列表","content":{"application/json":{"schema":{"type":"object","properties":{"channels":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"provider":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"configured":{"type":"boolean"},"implementationStatus":{"type":"string"},"capabilities":{"type":"array","items":{"type":"string"}}}}}}}}}}}}},"/api/payment-orders":{"post":{"tags":["Payments"],"summary":"创建支付订单","description":"REST 风格的商户下单接口。请求必须使用商户 API 凭证签名，并携带 x-novapay-key、x-novapay-timestamp、x-novapay-nonce、x-novapay-signature；写接口建议同时传入 Idempotency-Key 以保障安全重试。NovaPay 只会使用商户自有通道实例，并自动分配上游支付回调地址；如需商户业务通知请使用 callbackUrl；returnUrl 省略时将回到 NovaPay 托管结果页；正式使用官方通道前还需要补齐商户资料。","parameters":[{"in":"header","name":"x-novapay-key","required":true,"schema":{"type":"string"},"description":"商户 API 凭证 keyId。"},{"in":"header","name":"x-novapay-timestamp","required":true,"schema":{"type":"string"},"description":"参与 HMAC 签名的 ISO 时间戳或 Unix 时间戳。"},{"in":"header","name":"x-novapay-nonce","required":true,"schema":{"type":"string"},"description":"单次使用的随机串，用于防重放保护。"},{"in":"header","name":"x-novapay-signature","required":true,"schema":{"type":"string"},"description":"hex(hmac_sha256(secret, \"{timestamp}.{nonce}.{rawBody}\"))"},{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string"},"description":"商户写接口建议传入的幂等键。同一商户、同一业务操作作用域下，重复提交相同请求时将复用首次结果；同 key 对应不同请求体会返回冲突。"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderRequest"},"examples":{"alipay":{"value":{"merchantCode":"merchant-prod-cn-001","channelCode":"alipay.page","externalOrderId":"ORDER-20260410-001","amount":"88.00","subject":"NovaPay 正式支付订单","description":"支付宝网页支付"}},"wxpay":{"value":{"merchantCode":"merchant-prod-cn-001","channelCode":"wxpay.native","externalOrderId":"ORDER-20260410-002","amount":"18.80","subject":"NovaPay 微信 Native 订单"}}}}}},"responses":{"200":{"description":"订单已创建或命中幂等复用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentOrderResponse"}}}},"400":{"description":"请求体不合法","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"401":{"description":"商户签名校验失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"403":{"description":"商户未通过审核或未完成该通道所需资料，无法创建订单","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"404":{"description":"商户或通道不存在","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"409":{"description":"幂等键冲突，或相同幂等键请求仍在处理中","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"422":{"description":"通道尚未完成配置","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"500":{"description":"上游通道或服务端发生异常","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}}}}},"/api/payment-orders/{orderReference}":{"post":{"tags":["Payments"],"summary":"查询支付订单","description":"按资源路径查询当前支付订单状态，并默认同步最新的上游支付状态到 NovaPay。为了保持商户签名口径统一，这里仍使用 POST + JSON body。","parameters":[{"in":"path","name":"orderReference","required":true,"schema":{"type":"string"},"description":"订单引用，可传平台订单号或商户订单号。"},{"in":"header","name":"x-novapay-key","required":true,"schema":{"type":"string"},"description":"商户 API 凭证 keyId。"},{"in":"header","name":"x-novapay-timestamp","required":true,"schema":{"type":"string"},"description":"参与 HMAC 签名的 ISO 时间戳或 Unix 时间戳。"},{"in":"header","name":"x-novapay-nonce","required":true,"schema":{"type":"string"},"description":"单次使用的随机串，用于防重放保护。"},{"in":"header","name":"x-novapay-signature","required":true,"schema":{"type":"string"},"description":"hex(hmac_sha256(secret, \"{timestamp}.{nonce}.{rawBody}\"))"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryOrderByPathRequest"},"examples":{"queryOrder":{"value":{"merchantCode":"merchant-prod-cn-001","sync":true}}}}}},"responses":{"200":{"description":"最新订单状态","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentOrderResponse"}}}},"400":{"description":"请求体不合法","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"401":{"description":"商户签名校验失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"404":{"description":"商户或订单不存在","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"500":{"description":"上游通道或服务端发生异常","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}}}}},"/api/payment-orders/{orderReference}/close":{"post":{"tags":["Payments"],"summary":"关闭未支付订单","description":"按资源路径关闭一笔未支付订单，并同步更新 NovaPay 本地订单状态。为了保持商户签名口径统一，这里仍使用 POST + JSON body；写接口建议同时传入 Idempotency-Key 以保障安全重试。","parameters":[{"in":"path","name":"orderReference","required":true,"schema":{"type":"string"},"description":"订单引用，可传平台订单号或商户订单号。"},{"in":"header","name":"x-novapay-key","required":true,"schema":{"type":"string"},"description":"商户 API 凭证 keyId。"},{"in":"header","name":"x-novapay-timestamp","required":true,"schema":{"type":"string"},"description":"参与 HMAC 签名的 ISO 时间戳或 Unix 时间戳。"},{"in":"header","name":"x-novapay-nonce","required":true,"schema":{"type":"string"},"description":"单次使用的随机串，用于防重放保护。"},{"in":"header","name":"x-novapay-signature","required":true,"schema":{"type":"string"},"description":"hex(hmac_sha256(secret, \"{timestamp}.{nonce}.{rawBody}\"))"},{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string"},"description":"商户写接口建议传入的幂等键。同一商户、同一业务操作作用域下，重复提交相同请求时将复用首次结果；同 key 对应不同请求体会返回冲突。"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloseOrderByPathRequest"},"examples":{"closeOrder":{"value":{"merchantCode":"merchant-prod-cn-001"}}}}}},"responses":{"200":{"description":"关闭后的订单状态","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentOrderResponse"}}}},"400":{"description":"请求体不合法","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"401":{"description":"商户签名校验失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"404":{"description":"商户或订单不存在","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"409":{"description":"订单已支付成功、当前不可关闭，或幂等键冲突/处理中","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"422":{"description":"当前通道不支持关闭订单","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"500":{"description":"上游通道或服务端发生异常","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}}}}},"/api/payment-orders/{orderReference}/refunds":{"post":{"tags":["Payments"],"summary":"创建退款","description":"按订单资源路径为已支付订单创建退款。上游退款状态会被持久化保存，后续可继续查询异步退款结果；写接口建议同时传入 Idempotency-Key 以保障安全重试。","parameters":[{"in":"path","name":"orderReference","required":true,"schema":{"type":"string"},"description":"订单引用，可传平台订单号或商户订单号。"},{"in":"header","name":"x-novapay-key","required":true,"schema":{"type":"string"},"description":"商户 API 凭证 keyId。"},{"in":"header","name":"x-novapay-timestamp","required":true,"schema":{"type":"string"},"description":"参与 HMAC 签名的 ISO 时间戳或 Unix 时间戳。"},{"in":"header","name":"x-novapay-nonce","required":true,"schema":{"type":"string"},"description":"单次使用的随机串，用于防重放保护。"},{"in":"header","name":"x-novapay-signature","required":true,"schema":{"type":"string"},"description":"hex(hmac_sha256(secret, \"{timestamp}.{nonce}.{rawBody}\"))"},{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string"},"description":"商户写接口建议传入的幂等键。同一商户、同一业务操作作用域下，重复提交相同请求时将复用首次结果；同 key 对应不同请求体会返回冲突。"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRefundForOrderRequest"},"examples":{"partialRefund":{"value":{"merchantCode":"merchant-prod-cn-001","externalRefundId":"REFUND-20260410-001","amount":"8.80","reason":"用户申请退款"}}}}}},"responses":{"200":{"description":"退款已创建或命中幂等复用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRefundResponse"}}}},"400":{"description":"请求体不合法","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"401":{"description":"商户签名校验失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"404":{"description":"商户或订单不存在","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"409":{"description":"订单当前不可退款、退款单号发生冲突，或幂等键冲突/处理中","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"422":{"description":"退款金额超过可退余额，或当前通道不支持退款","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"500":{"description":"上游通道或服务端发生异常","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}}}}},"/api/payment-refunds/{refundReference}":{"post":{"tags":["Payments"],"summary":"查询退款","description":"按资源路径查询当前退款状态，并默认同步最新的上游退款状态到 NovaPay。为了保持商户签名口径统一，这里仍使用 POST + JSON body。","parameters":[{"in":"path","name":"refundReference","required":true,"schema":{"type":"string"},"description":"退款引用，可传平台退款号或商户退款单号。"},{"in":"header","name":"x-novapay-key","required":true,"schema":{"type":"string"},"description":"商户 API 凭证 keyId。"},{"in":"header","name":"x-novapay-timestamp","required":true,"schema":{"type":"string"},"description":"参与 HMAC 签名的 ISO 时间戳或 Unix 时间戳。"},{"in":"header","name":"x-novapay-nonce","required":true,"schema":{"type":"string"},"description":"单次使用的随机串，用于防重放保护。"},{"in":"header","name":"x-novapay-signature","required":true,"schema":{"type":"string"},"description":"hex(hmac_sha256(secret, \"{timestamp}.{nonce}.{rawBody}\"))"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryRefundByPathRequest"},"examples":{"queryRefund":{"value":{"merchantCode":"merchant-prod-cn-001","sync":true}}}}}},"responses":{"200":{"description":"最新退款状态","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRefundResponse"}}}},"400":{"description":"请求体不合法","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"401":{"description":"商户签名校验失败","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"404":{"description":"商户或退款不存在","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"500":{"description":"上游通道或服务端发生异常","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}}}}},"/api/payments/callback/alipay/{accountId}/{token}":{"post":{"tags":["Callbacks"],"summary":"支付宝商户实例回调接口","parameters":[{"in":"path","name":"accountId","required":true,"schema":{"type":"string"}},{"in":"path","name":"token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"回调处理成功后返回纯文本 success"},"400":{"description":"支付宝回调参数不合法","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"404":{"description":"商户通道实例或订单不存在","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}}}},"get":{"tags":["Callbacks"],"summary":"支付宝商户实例回调调试接口（Query String）","parameters":[{"in":"path","name":"accountId","required":true,"schema":{"type":"string"}},{"in":"path","name":"token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"回调处理成功后返回纯文本 success"},"400":{"description":"支付宝回调参数不合法","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"404":{"description":"商户通道实例或订单不存在","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}}}}},"/api/payments/callback/wxpay/{accountId}/{token}":{"post":{"tags":["Callbacks"],"summary":"微信支付商户实例回调接口","description":"接收商户自有微信支付通道实例的 API v3 回调，校验响应签名、解密加密资源，并更新对应支付订单状态。","parameters":[{"in":"path","name":"accountId","required":true,"schema":{"type":"string"}},{"in":"path","name":"token","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"回调已受理"},"400":{"description":"微信支付回调参数不合法","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"404":{"description":"商户通道实例或订单不存在","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}}}}},"/api/admin/merchants":{"get":{"tags":["Admin"],"summary":"获取商户列表","security":[{"AdminSessionCookie":[]}],"parameters":[{"in":"query","name":"code","schema":{"type":"string"},"required":false}],"responses":{"200":{"description":"商户列表","content":{"application/json":{"schema":{"type":"object","properties":{"merchants":{"type":"array","items":{"$ref":"#/components/schemas/Merchant"}}}}}}},"401":{"description":"未授权的后台请求","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}}}},"post":{"tags":["Admin"],"summary":"创建商户","security":[{"AdminSessionCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code","name"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED","SUSPENDED"]},"legalName":{"type":["string","null"]},"contactName":{"type":["string","null"]},"contactEmail":{"type":["string","null"]},"contactPhone":{"type":["string","null"]},"companyRegistrationId":{"type":["string","null"]},"onboardingNote":{"type":["string","null"]},"reviewNote":{"type":["string","null"]},"callbackBase":{"type":["string","null"],"format":"uri"},"notifySecret":{"type":["string","null"]},"apiIpWhitelist":{"type":["string","null"]},"callbackEnabled":{"type":"boolean"}}}}}},"responses":{"201":{"description":"商户已创建","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Merchant"}}}},"400":{"description":"商户请求参数不合法","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}},"401":{"description":"未授权的后台请求","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}}}}},"/api/admin/merchants/{id}":{"get":{"tags":["Admin"],"summary":"获取商户详情","security":[{"AdminSessionCookie":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"商户详情","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Merchant"}}}},"404":{"description":"商户不存在","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}}}},"put":{"tags":["Admin"],"summary":"更新商户","security":[{"AdminSessionCookie":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED","SUSPENDED"]},"legalName":{"type":["string","null"]},"contactName":{"type":["string","null"]},"contactEmail":{"type":["string","null"]},"contactPhone":{"type":["string","null"]},"companyRegistrationId":{"type":["string","null"]},"onboardingNote":{"type":["string","null"]},"reviewNote":{"type":["string","null"]},"callbackBase":{"type":["string","null"],"format":"uri"},"notifySecret":{"type":["string","null"]},"apiIpWhitelist":{"type":["string","null"]},"callbackEnabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"商户已更新","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Merchant"}}}},"404":{"description":"商户不存在","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}}}}},"/api/admin/merchant-channel-bindings":{"get":{"tags":["Admin"],"summary":"获取商户通道路由列表","security":[{"AdminSessionCookie":[]}],"parameters":[{"in":"query","name":"merchantCode","schema":{"type":"string"}}],"responses":{"200":{"description":"路由绑定列表"}}},"post":{"tags":["Admin"],"summary":"创建或更新商户通道路由","security":[{"AdminSessionCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["merchantCode","channelCode"],"properties":{"merchantCode":{"type":"string"},"channelCode":{"type":"string"},"enabled":{"type":"boolean"},"merchantChannelAccountId":{"type":["string","null"]},"minAmount":{"oneOf":[{"type":"string"},{"type":"number"}]},"maxAmount":{"oneOf":[{"type":"string"},{"type":"number"}]},"feeRate":{"oneOf":[{"type":"string"},{"type":"number"}]}}}}}},"responses":{"201":{"description":"路由绑定已保存"}}}},"/api/admin/system-config":{"get":{"tags":["Admin"],"summary":"获取系统配置","security":[{"AdminSessionCookie":[]}],"responses":{"200":{"description":"系统配置项列表","content":{"application/json":{"schema":{"type":"object","properties":{"configs":{"type":"array","items":{"$ref":"#/components/schemas/SystemConfigItem"}}}}}}}}},"put":{"tags":["Admin"],"summary":"批量更新系统配置","security":[{"AdminSessionCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["configs"],"properties":{"configs":{"type":"array","items":{"type":"object","required":["key","value"],"properties":{"key":{"type":"string"},"value":{"type":"string"},"group":{"type":"string"},"label":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"系统配置已更新"}}}},"/api/admin/payment-orders/{id}/retry-callback":{"post":{"tags":["Admin"],"summary":"重试商户业务回调","security":[{"AdminSessionCookie":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"重试结果"},"404":{"description":"支付订单不存在","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}}}}}}}}}}