接口地址
/api/health
get
健康检查
响应说明
200
服务与数据库状态
响应结构展开查看
{
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"database": {
"type": "string"
}
}
}接口文档
NovaPay 站内 API 文档
这里直接展示项目当前的 OpenAPI 规范，覆盖支付下单、回调、商户后台配置接口。原始 JSON 规范也可直接读取，方便后续接入 Swagger、Postman 或 SDK 生成工具。
本文档现在优先展示 REST 风格资源路径；历史 `/api/payments/...` 动作型接口仍继续兼容，但不再作为主接入路径展示。
规范总览
- OpenAPI
- 3.1.0
- 版本
- 0.1.0
- 服务地址
- https://pay.muyuai.top
- 鉴权说明
- 后台接口使用管理员会话 Cookie，商户接口使用 `x-novapay-key`、`x-novapay-timestamp`、`x-novapay-nonce`、`x-novapay-signature`，写接口建议再叠加 `Idempotency-Key`，并可结合 IP 白名单。
商户签名
x-novapay-signature = hex(
hmac_sha256(apiSecret, "{timestamp}.{nonce}.{rawBody}")
)商户接口必须使用独立 API 凭证签名，并保证 `x-novapay-nonce` 单次请求唯一。商户写接口建议同时传入 `Idempotency-Key` 以保障安全重试。回调通知则使用 `notifySecret` 验签。
上游支付回调地址会按商户通道实例自动生成，下单不要传 `notifyUrl`。如需接收商户业务通知，请使用默认业务回调地址或单笔 `callbackUrl`；`returnUrl` 仅用于浏览器跳转，不传时系统会回到 NovaPay 托管结果页。
接口地址
/api/channels
get
列出支付通道
响应说明
200
可用支付通道列表
响应结构展开查看
{
"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
创建支付订单
REST 风格的商户下单接口。请求必须使用商户 API 凭证签名，并携带 x-novapay-key、x-novapay-timestamp、x-novapay-nonce、x-novapay-signature；写接口建议同时传入 Idempotency-Key 以保障安全重试。NovaPay 只会使用商户自有通道实例，并自动分配上游支付回调地址；如需商户业务通知请使用 callbackUrl；returnUrl 省略时将回到 NovaPay 托管结果页；正式使用官方通道前还需要补齐商户资料。
请求参数
header: x-novapay-keyheader: x-novapay-timestampheader: x-novapay-nonceheader: x-novapay-signatureheader: Idempotency-Key
请求结构展开查看
{
"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
}
}
}响应说明
200
订单已创建或命中幂等复用
响应结构展开查看
{
"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"
}
}
}
}
}
}
}400
请求体不合法
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}401
商户签名校验失败
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}403
商户未通过审核或未完成该通道所需资料，无法创建订单
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}404
商户或通道不存在
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}409
幂等键冲突，或相同幂等键请求仍在处理中
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}422
通道尚未完成配置
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}500
上游通道或服务端发生异常
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}接口地址
/api/payment-orders/{orderReference}
post
查询支付订单
按资源路径查询当前支付订单状态，并默认同步最新的上游支付状态到 NovaPay。为了保持商户签名口径统一，这里仍使用 POST + JSON body。
请求参数
path: orderReferenceheader: x-novapay-keyheader: x-novapay-timestampheader: x-novapay-nonceheader: x-novapay-signature
请求结构展开查看
{
"type": "object",
"required": [
"merchantCode"
],
"properties": {
"merchantCode": {
"type": "string"
},
"sync": {
"type": "boolean"
}
}
}响应说明
200
最新订单状态
响应结构展开查看
{
"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"
}
}
}
}
}
}
}400
请求体不合法
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}401
商户签名校验失败
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}404
商户或订单不存在
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}500
上游通道或服务端发生异常
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}接口地址
/api/payment-orders/{orderReference}/close
post
关闭未支付订单
按资源路径关闭一笔未支付订单，并同步更新 NovaPay 本地订单状态。为了保持商户签名口径统一，这里仍使用 POST + JSON body；写接口建议同时传入 Idempotency-Key 以保障安全重试。
请求参数
path: orderReferenceheader: x-novapay-keyheader: x-novapay-timestampheader: x-novapay-nonceheader: x-novapay-signatureheader: Idempotency-Key
请求结构展开查看
{
"type": "object",
"required": [
"merchantCode"
],
"properties": {
"merchantCode": {
"type": "string"
}
}
}响应说明
200
关闭后的订单状态
响应结构展开查看
{
"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"
}
}
}
}
}
}
}400
请求体不合法
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}401
商户签名校验失败
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}404
商户或订单不存在
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}409
订单已支付成功、当前不可关闭，或幂等键冲突/处理中
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}422
当前通道不支持关闭订单
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}500
上游通道或服务端发生异常
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}接口地址
/api/payment-orders/{orderReference}/refunds
post
创建退款
按订单资源路径为已支付订单创建退款。上游退款状态会被持久化保存，后续可继续查询异步退款结果；写接口建议同时传入 Idempotency-Key 以保障安全重试。
请求参数
path: orderReferenceheader: x-novapay-keyheader: x-novapay-timestampheader: x-novapay-nonceheader: x-novapay-signatureheader: Idempotency-Key
请求结构展开查看
{
"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
}
}
}响应说明
200
退款已创建或命中幂等复用
响应结构展开查看
{
"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"
}
}
}
}
}400
请求体不合法
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}401
商户签名校验失败
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}404
商户或订单不存在
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}409
订单当前不可退款、退款单号发生冲突，或幂等键冲突/处理中
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}422
退款金额超过可退余额，或当前通道不支持退款
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}500
上游通道或服务端发生异常
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}接口地址
/api/payment-refunds/{refundReference}
post
查询退款
按资源路径查询当前退款状态，并默认同步最新的上游退款状态到 NovaPay。为了保持商户签名口径统一，这里仍使用 POST + JSON body。
请求参数
path: refundReferenceheader: x-novapay-keyheader: x-novapay-timestampheader: x-novapay-nonceheader: x-novapay-signature
请求结构展开查看
{
"type": "object",
"required": [
"merchantCode"
],
"properties": {
"merchantCode": {
"type": "string"
},
"sync": {
"type": "boolean"
}
}
}响应说明
200
最新退款状态
响应结构展开查看
{
"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"
}
}
}
}
}400
请求体不合法
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}401
商户签名校验失败
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}404
商户或退款不存在
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}500
上游通道或服务端发生异常
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}接口地址
/api/payments/callback/alipay/{accountId}/{token}
post
支付宝商户实例回调接口
请求参数
path: accountIdpath: token
响应说明
200
回调处理成功后返回纯文本 success
400
支付宝回调参数不合法
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}404
商户通道实例或订单不存在
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}get
支付宝商户实例回调调试接口（Query String）
请求参数
path: accountIdpath: token
响应说明
200
回调处理成功后返回纯文本 success
400
支付宝回调参数不合法
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}404
商户通道实例或订单不存在
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}接口地址
/api/payments/callback/wxpay/{accountId}/{token}
post
微信支付商户实例回调接口
接收商户自有微信支付通道实例的 API v3 回调，校验响应签名、解密加密资源，并更新对应支付订单状态。
请求参数
path: accountIdpath: token
响应说明
204
回调已受理
400
微信支付回调参数不合法
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}404
商户通道实例或订单不存在
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}接口地址
/api/admin/merchants
get
获取商户列表
请求参数
query: code
响应说明
200
商户列表
响应结构展开查看
{
"type": "object",
"properties": {
"merchants": {
"type": "array",
"items": {
"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"
}
}
}
}
}
}401
未授权的后台请求
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}post
创建商户
请求结构展开查看
{
"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"
}
}
}响应说明
201
商户已创建
响应结构展开查看
{
"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"
}
}
}400
商户请求参数不合法
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}401
未授权的后台请求
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}接口地址
/api/admin/merchants/{id}
get
获取商户详情
请求参数
path: id
响应说明
200
商户详情
响应结构展开查看
{
"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"
}
}
}404
商户不存在
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}put
更新商户
请求参数
path: id
请求结构展开查看
{
"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"
}
}
}响应说明
200
商户已更新
响应结构展开查看
{
"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"
}
}
}404
商户不存在
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}接口地址
/api/admin/merchant-channel-bindings
get
获取商户通道路由列表
请求参数
query: merchantCode
响应说明
200
路由绑定列表
post
创建或更新商户通道路由
请求结构展开查看
{
"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"
}
]
}
}
}响应说明
201
路由绑定已保存
接口地址
/api/admin/system-config
get
获取系统配置
响应说明
200
系统配置项列表
响应结构展开查看
{
"type": "object",
"properties": {
"configs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
},
"group": {
"type": "string"
},
"label": {
"type": [
"string",
"null"
]
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}put
批量更新系统配置
请求结构展开查看
{
"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"
}
}
}
}
}
}响应说明
200
系统配置已更新
接口地址
/api/admin/payment-orders/{id}/retry-callback
post
重试商户业务回调
请求参数
path: id
响应说明
200
重试结果
404
支付订单不存在
响应结构展开查看
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"details": {}
}
}