Unipay 代理商户 API

本页面是完整接入说明。接入商户无需下载 YAML 文件，也可以仅通过官网文档完成接口接入。

概览

商户模型

代理商户使用上游透明选路。请求不传上游路由字段，后端按所属 ISV 的启用渠道自动选择。

示例中的 sign 为占位符，实际请求需按签名规则使用真实字段生成。

响应信封

字段	类型	必填	说明
`code`	integer(int32)	是	业务状态码
`msg`	string	是	业务提示信息
`data`	object\|null	否	业务响应数据
`sign`	string	否	响应签名（平台私钥签名）
`resTime`	string(date-time)	否	响应时间
`traceId`	string	否	链路追踪ID

接口列表

路径	API	说明
`POST /unipay/pay`	支付接口	创建 Mexico 虚拟账户入金订单并发起支付。
`POST /unipay/options/pay-methods`	查询支付 method 列表	查询当前商户支付接口可使用的 method 列表。
`POST /unipay/options/payee-types`	查询转账 payeeType 列表	查询当前商户转账接口可使用的 payeeType 列表。
`POST /unipay/options/payee-codes`	查询转账 payeeCode 列表	按 payeeType 查询当前商户可使用的系统公开 payeeCode 列表。
`POST /unipay/close`	关闭和撤销接口	关闭未完成的支付订单，必要时使用撤销方式。
`POST /unipay/inqury`	转账预查询接口	在转账前校验收款账户有效性。
`POST /unipay/transfer`	转账接口	创建并提交转账订单。
`POST /unipay/query/payOrder`	支付订单查询接口	查询支付订单当前状态和明细。
`POST /unipay/query/transferOrder`	转账订单查询接口	查询转账订单当前状态和明细。
`POST /unipay/sync/order/pay`	支付订单同步接口	主动向上游同步支付订单状态并调整本地订单。

支付接口

创建 Mexico 虚拟账户入金订单并发起支付。

商户系统生成业务订单后调用，method 固定使用 mex_virtual_account，平台返回支付订单号、支付状态和虚拟账户支付参数体。

请求信息

字段	说明
方法	POST
路径	`/unipay/pay`
Content-Type	`application/json`

公共请求参数

字段	类型	必填	约束	说明
`mchNo`	string	是	maxLength=32	商户号
`appId`	string	否	maxLength=32	应用号
`reqTime`	string(date-time)	是	yyyy-MM-dd HH:mm:ss	请求时间, 格式yyyy-MM-dd HH:mm:ss
`nonceStr`	string	否	maxLength=32	随机数
`sign`	string	是	maxLength=1024	签名
`clientIp`	string	否	maxLength=64	客户端ip

业务参数

字段	类型	必填	约束	说明
`bizOrderNo`	string	是	minLength=1, maxLength=100	商户订单号
`title`	string	是	minLength=1, maxLength=100	支付标题
`description`	string	否	maxLength=50	支付描述
`expiredTime`	string(date-time)	否	无	过期时间
`method`	string	是	minLength=1, maxLength=32	支付方式编码
`limitPay`	string	否	maxLength=128	限制用户支付类型
`amount`	number(double)	是	minimum=0.01	支付金额
`extraParam`	string	否	maxLength=2048	支付扩展参数
`attach`	string	否	maxLength=500	商户扩展参数
`returnUrl`	string	否	maxLength=200	同步通知URL
`quitUrl`	string	否	maxLength=200	退出地址
`notifyUrl`	string	否	maxLength=200	异步通知地址

请求示例

json

{
  "clientIp": "127.0.0.1",
  "nonceStr": "nonce-20260414-001",
  "sign": "<BASE64_RSA_SIGNATURE>",
  "reqTime": "2026-04-14 12:00:00",
  "mchNo": "M2026000001",
  "appId": "APP20260001",
  "bizOrderNo": "BIZ-PAY-20260414-001",
  "title": "Order Payment",
  "description": "Payment for order #001",
  "expiredTime": "2026-04-14 12:00:00",
  "method": "mex_virtual_account",
  "limitPay": "string",
  "amount": 12.5,
  "extraParam": "{\"scene\":\"mobile\"}",
  "attach": "{\"orderTag\":\"vip\"}",
  "returnUrl": "https://merchant.example.com/return",
  "quitUrl": "https://merchant.example.com/quit",
  "notifyUrl": "https://merchant.example.com/callback"
}

响应 data 字段

字段	类型	必填	说明
`bizOrderNo`	string	否	商户订单号
`orderNo`	string	否	订单号
`status`	string	否	支付状态
`payBody`	string	否	支付参数体

常用取值

支付方式 method

value	说明
`mex_virtual_account`	MEX 虚拟账户入金

限制支付 limitPay

value	说明
`no_credit`	限制信用卡支付

支付状态 status/orderStatus

value	说明
`wait`	待支付
`progress`	支付中
`success`	成功
`close`	支付关闭
`cancel`	支付撤销
`fail`	失败
`timeout`	支付超时

成功响应示例

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "bizOrderNo": "BIZ-PAY-20260414-001",
    "orderNo": "P202604140001",
    "status": "success",
    "payBody": "{\"qrCode\":\"https://...\"}"
  },
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

失败响应示例

json

{
  "code": 20052,
  "msg": "验签失败",
  "data": null,
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

Callback 回调通知

支付订单回调

平台在订单状态变化后向请求中的 notifyUrl 发起 POST 回调，Content-Type 为 application/json。

请求体结构为 DaxNoticeResult<PayOrderResult>，data 字段与订单查询接口返回字段一致。

平台使用平台私钥生成 sign，商户需使用平台公钥验签。商户处理成功必须返回纯文本 SUCCESS（大小写不敏感），否则视为失败。

平台回调超时时间为 15 秒，失败后自动重试最多 16 次。商户侧应按平台订单号或商户业务单号做幂等处理。

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "bizOrderNo": "BIZ-PAY-20260414-001",
    "orderNo": "P202604140001",
    "title": "Order Payment",
    "description": "Payment for order #001",
    "method": "mex_virtual_account",
    "limitPay": "string",
    "amount": 12.5,
    "fee": 0.01,
    "realAmount": 0.01,
    "status": "success",
    "settleStatus": "not_settle",
    "settleType": "D+1",
    "settleTime": "2026-04-14 12:00:00",
    "payTime": "2026-04-14 12:00:00",
    "closeTime": "2026-04-14 12:00:00",
    "expiredTime": "2026-04-14 12:00:00",
    "attach": "{\"orderTag\":\"vip\"}"
  },
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a",
  "noticeType": "order_status_changed",
  "mchNo": "M2026000001",
  "appId": "APP20260001"
}

商户响应

text

SUCCESS

查询支付 method 列表

查询当前商户支付接口可使用的 method 列表。

商户在展示支付方式、组装支付请求前调用。代理商户返回公开支付方式，不暴露实际命中的上游通道。

请求信息

字段	说明
方法	POST
路径	`/unipay/options/pay-methods`
Content-Type	`application/json`

公共请求参数

字段	类型	必填	约束	说明
`mchNo`	string	是	maxLength=32	商户号
`appId`	string	否	maxLength=32	应用号
`reqTime`	string(date-time)	是	yyyy-MM-dd HH:mm:ss	请求时间, 格式yyyy-MM-dd HH:mm:ss
`nonceStr`	string	否	maxLength=32	随机数
`sign`	string	是	maxLength=1024	签名
`clientIp`	string	否	maxLength=64	客户端ip

业务参数

无

请求示例

json

{
  "clientIp": "127.0.0.1",
  "nonceStr": "nonce-20260414-001",
  "sign": "<BASE64_RSA_SIGNATURE>",
  "reqTime": "2026-04-14 12:00:00",
  "mchNo": "M2026000001",
  "appId": "APP20260001"
}

响应 data 字段

字段	类型	必填	说明
`code`	string	否	编码
`name`	string	否	名称

成功响应示例

json

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "code": "mex_virtual_account",
      "name": "MEX虚拟账户入金"
    }
  ],
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

失败响应示例

json

{
  "code": 20052,
  "msg": "验签失败",
  "data": null,
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

查询转账 payeeType 列表

查询当前商户转账接口可使用的 payeeType 列表。

商户在展示转账收款类型、组装预查询或转账请求前调用。

请求信息

字段	说明
方法	POST
路径	`/unipay/options/payee-types`
Content-Type	`application/json`

公共请求参数

字段	类型	必填	约束	说明
`mchNo`	string	是	maxLength=32	商户号
`appId`	string	否	maxLength=32	应用号
`reqTime`	string(date-time)	是	yyyy-MM-dd HH:mm:ss	请求时间, 格式yyyy-MM-dd HH:mm:ss
`nonceStr`	string	否	maxLength=32	随机数
`sign`	string	是	maxLength=1024	签名
`clientIp`	string	否	maxLength=64	客户端ip

业务参数

无

请求示例

json

{
  "clientIp": "127.0.0.1",
  "nonceStr": "nonce-20260414-001",
  "sign": "<BASE64_RSA_SIGNATURE>",
  "reqTime": "2026-04-14 12:00:00",
  "mchNo": "M2026000001",
  "appId": "APP20260001"
}

响应 data 字段

字段	类型	必填	说明
`code`	string	否	编码
`name`	string	否	名称

成功响应示例

json

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "code": "spei_transfer",
      "name": "SPEI 转账"
    }
  ],
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

失败响应示例

json

{
  "code": 20052,
  "msg": "验签失败",
  "data": null,
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

查询转账 payeeCode 列表

按 payeeType 查询当前商户可使用的系统公开 payeeCode 列表。

当 payeeType 需要银行代码或收款机构代码时调用，返回值可直接用于预查询和转账请求；不要传 OPM/Fintoc 上游原始编码。

请求信息

字段	说明
方法	POST
路径	`/unipay/options/payee-codes`
Content-Type	`application/json`

公共请求参数

字段	类型	必填	约束	说明
`mchNo`	string	是	maxLength=32	商户号
`appId`	string	否	maxLength=32	应用号
`reqTime`	string(date-time)	是	yyyy-MM-dd HH:mm:ss	请求时间, 格式yyyy-MM-dd HH:mm:ss
`nonceStr`	string	否	maxLength=32	随机数
`sign`	string	是	maxLength=1024	签名
`clientIp`	string	否	maxLength=64	客户端ip

业务参数

字段	类型	必填	约束	说明
`payeeType`	string	是	minLength=1, maxLength=32	收款人类型

请求示例

json

{
  "clientIp": "127.0.0.1",
  "nonceStr": "nonce-20260414-001",
  "sign": "<BASE64_RSA_SIGNATURE>",
  "reqTime": "2026-04-14 12:00:00",
  "mchNo": "M2026000001",
  "appId": "APP20260001",
  "payeeType": "spei_transfer"
}

响应 data 字段

字段	类型	必填	说明
`code`	string	否	编码
`name`	string	否	名称

成功响应示例

json

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "code": "mx_banxico",
      "name": "BANXICO"
    }
  ],
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

失败响应示例

json

{
  "code": 20052,
  "msg": "验签失败",
  "data": null,
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

关闭和撤销接口

关闭未完成的支付订单，必要时使用撤销方式。

订单超时、用户取消或商户主动终止支付时调用。订单号、商户订单号、上游订单号至少传一个。

请求信息

字段	说明
方法	POST
路径	`/unipay/close`
Content-Type	`application/json`

公共请求参数

字段	类型	必填	约束	说明
`mchNo`	string	是	maxLength=32	商户号
`appId`	string	否	maxLength=32	应用号
`reqTime`	string(date-time)	是	yyyy-MM-dd HH:mm:ss	请求时间, 格式yyyy-MM-dd HH:mm:ss
`nonceStr`	string	否	maxLength=32	随机数
`sign`	string	是	maxLength=1024	签名
`clientIp`	string	否	maxLength=64	客户端ip

业务参数

字段	类型	必填	约束	说明
`orderNo`	string	否	maxLength=100	订单号
`bizOrderNo`	string	否	maxLength=100	商户订单号
`useCancel`	boolean	否	无	是否使用撤销方式进行订单关闭

请求示例

json

{
  "clientIp": "127.0.0.1",
  "nonceStr": "nonce-20260414-001",
  "sign": "<BASE64_RSA_SIGNATURE>",
  "reqTime": "2026-04-14 12:00:00",
  "mchNo": "M2026000001",
  "appId": "APP20260001",
  "orderNo": "P202604140001",
  "bizOrderNo": "BIZ-PAY-20260414-001",
  "useCancel": true
}

响应 data 字段

data 成功时为 null。

成功响应示例

json

{
  "code": 0,
  "msg": "success",
  "data": null,
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

失败响应示例

json

{
  "code": 20052,
  "msg": "验签失败",
  "data": null,
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

转账预查询接口

在转账前校验收款账户有效性。

适用于银行账号、SPEI 等需要先确认账户可用性的转账场景。

请求信息

字段	说明
方法	POST
路径	`/unipay/inqury`
Content-Type	`application/json`

公共请求参数

字段	类型	必填	约束	说明
`mchNo`	string	是	maxLength=32	商户号
`appId`	string	否	maxLength=32	应用号
`reqTime`	string(date-time)	是	yyyy-MM-dd HH:mm:ss	请求时间, 格式yyyy-MM-dd HH:mm:ss
`nonceStr`	string	否	maxLength=32	随机数
`sign`	string	是	maxLength=1024	签名
`clientIp`	string	否	maxLength=64	客户端ip

业务参数

字段	类型	必填	约束	说明
`bizInquryNo`	string	是	minLength=1, maxLength=100	商户查询号
`payeeType`	string	是	minLength=1, maxLength=32	收款人账号类型
`payeeAccount`	string	是	minLength=1, maxLength=100	收款人账号
`payeeName`	string	否	maxLength=50	上传的收款人姓名
`payeeCode`	string	否	maxLength=64	收款编码(如银行代码)
`extraParam`	string	否	maxLength=2048	查询扩展参数
`attach`	string	否	maxLength=500	商户扩展参数

请求示例

json

{
  "clientIp": "127.0.0.1",
  "nonceStr": "nonce-20260414-001",
  "sign": "<BASE64_RSA_SIGNATURE>",
  "reqTime": "2026-04-14 12:00:00",
  "mchNo": "M2026000001",
  "appId": "APP20260001",
  "bizInquryNo": "BIZ-INQURY-20260414-001",
  "payeeType": "spei_transfer",
  "payeeAccount": "6222020202020202",
  "payeeName": "ZHANG SAN",
  "payeeCode": "mx_banxico",
  "extraParam": "{\"scene\":\"mobile\"}",
  "attach": "{\"orderTag\":\"vip\"}"
}

响应 data 字段

字段	类型	必填	说明
`bizInquryNo`	string	否	商户查询号
`inquryNo`	string	否	查询号
`status`	string	否	状态
`accountValid`	boolean	否	账户是否有效
`uploadPayeeName`	string	否	上传账户名

常用取值

收款类型 payeeType

value	说明
`user_id`	用户 ID
`open_id`	OpenId
`login_name`	用户账号
`bank_card`	银行卡
`spei_transfer`	SPEI 转账

预查询状态 status

value	说明
`valid`	账户有效
`invalid`	账户无效
`unknown`	未知

成功响应示例

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "bizInquryNo": "BIZ-INQURY-20260414-001",
    "inquryNo": "string",
    "status": "valid",
    "accountValid": true,
    "uploadPayeeName": "ZHANG SAN"
  },
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

失败响应示例

json

{
  "code": 20052,
  "msg": "验签失败",
  "data": null,
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

转账接口

创建并提交转账订单。

适用于提现、付款到银行卡、SPEI 转账等出款场景。建议先调用预查询确认账户有效性。

请求信息

字段	说明
方法	POST
路径	`/unipay/transfer`
Content-Type	`application/json`

公共请求参数

字段	类型	必填	约束	说明
`mchNo`	string	是	maxLength=32	商户号
`appId`	string	否	maxLength=32	应用号
`reqTime`	string(date-time)	是	yyyy-MM-dd HH:mm:ss	请求时间, 格式yyyy-MM-dd HH:mm:ss
`nonceStr`	string	否	maxLength=32	随机数
`sign`	string	是	maxLength=1024	签名
`clientIp`	string	否	maxLength=64	客户端ip

业务参数

字段	类型	必填	约束	说明
`bizTransferNo`	string	是	minLength=1, maxLength=100	商户转账号
`amount`	number(double)	是	minimum=0.01	转账金额
`title`	string	否	maxLength=100	标题
`reason`	string	否	maxLength=50	转账原因/备注
`payeeType`	string	是	minLength=1, maxLength=32	收款人账号类型
`payeeAccount`	string	是	minLength=1, maxLength=100	收款人账号
`payeeName`	string	否	maxLength=50	收款人姓名
`payeeCode`	string	否	maxLength=64	收款编码(如银行代码)
`extraParam`	string	否	maxLength=2048	转账扩展参数
`attach`	string	否	maxLength=500	商户扩展参数,回调时会原样返回
`notifyUrl`	string	否	maxLength=200	回调通知地址

请求示例

json

{
  "clientIp": "127.0.0.1",
  "nonceStr": "nonce-20260414-001",
  "sign": "<BASE64_RSA_SIGNATURE>",
  "reqTime": "2026-04-14 12:00:00",
  "mchNo": "M2026000001",
  "appId": "APP20260001",
  "bizTransferNo": "BIZ-TRANSFER-20260414-001",
  "amount": 12.5,
  "title": "Order Payment",
  "reason": "Manual operation remark",
  "payeeType": "spei_transfer",
  "payeeAccount": "6222020202020202",
  "payeeName": "ZHANG SAN",
  "payeeCode": "mx_banxico",
  "extraParam": "{\"scene\":\"mobile\"}",
  "attach": "{\"orderTag\":\"vip\"}",
  "notifyUrl": "https://merchant.example.com/callback"
}

响应 data 字段

字段	类型	必填	说明
`bizTransferNo`	string	否	商户转账号
`transferNo`	string	否	转账号
`status`	string	否	状态

常用取值

收款类型 payeeType

value	说明
`user_id`	用户 ID
`open_id`	OpenId
`login_name`	用户账号
`bank_card`	银行卡
`spei_transfer`	SPEI 转账

转账状态 status/orderStatus

value	说明
`progress`	转账中
`success`	转账成功
`close`	转账关闭
`fail`	转账失败

成功响应示例

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "bizTransferNo": "BIZ-TRANSFER-20260414-001",
    "transferNo": "T202604140001",
    "status": "progress"
  },
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

失败响应示例

json

{
  "code": 20052,
  "msg": "验签失败",
  "data": null,
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

Callback 回调通知

转账订单回调

平台在订单状态变化后向请求中的 notifyUrl 发起 POST 回调，Content-Type 为 application/json。

请求体结构为 DaxNoticeResult<TransferOrderResult>，data 字段与订单查询接口返回字段一致。

平台使用平台私钥生成 sign，商户需使用平台公钥验签。商户处理成功必须返回纯文本 SUCCESS（大小写不敏感），否则视为失败。

平台回调超时时间为 15 秒，失败后自动重试最多 16 次。商户侧应按平台订单号或商户业务单号做幂等处理。

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "bizTransferNo": "BIZ-TRANSFER-20260414-001",
    "transferNo": "T202604140001",
    "amount": 12.5,
    "fee": 0.01,
    "title": "Order Payment",
    "reason": "Manual operation remark",
    "payeeType": "spei_transfer",
    "payeeAccount": "6222020202020202",
    "payeeName": "ZHANG SAN",
    "payeeCode": "mx_banxico",
    "status": "success",
    "finishTime": "2026-04-14 12:00:00",
    "attach": "{\"orderTag\":\"vip\"}"
  },
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a",
  "noticeType": "order_status_changed",
  "mchNo": "M2026000001",
  "appId": "APP20260001"
}

商户响应

text

SUCCESS

支付订单查询接口

查询支付订单当前状态和明细。

支付结果不确定、回调未收到或需要对账时调用。

请求信息

字段	说明
方法	POST
路径	`/unipay/query/payOrder`
Content-Type	`application/json`

公共请求参数

字段	类型	必填	约束	说明
`mchNo`	string	是	maxLength=32	商户号
`appId`	string	否	maxLength=32	应用号
`reqTime`	string(date-time)	是	yyyy-MM-dd HH:mm:ss	请求时间, 格式yyyy-MM-dd HH:mm:ss
`nonceStr`	string	否	maxLength=32	随机数
`sign`	string	是	maxLength=1024	签名
`clientIp`	string	否	maxLength=64	客户端ip

业务参数

字段	类型	必填	约束	说明
`orderNo`	string	否	maxLength=100	订单号
`bizOrderNo`	string	否	maxLength=100	商户订单号

请求示例

json

{
  "clientIp": "127.0.0.1",
  "nonceStr": "nonce-20260414-001",
  "sign": "<BASE64_RSA_SIGNATURE>",
  "reqTime": "2026-04-14 12:00:00",
  "mchNo": "M2026000001",
  "appId": "APP20260001",
  "orderNo": "P202604140001",
  "bizOrderNo": "BIZ-PAY-20260414-001"
}

响应 data 字段

字段	类型	必填	说明
`bizOrderNo`	string	否	商户订单号
`orderNo`	string	否	支付订单号
`title`	string	否	标题
`description`	string	否	描述
`method`	string	否	支付方式
`limitPay`	string	否	限制用户支付类型
`amount`	number(double)	否	金额
`fee`	number(double)	否	手续费
`realAmount`	number(double)	否	实收金额
`status`	string	否	支付状态
`settleStatus`	string	否	结算状态
`settleType`	string	否	结算类型
`settleTime`	string(date-time)	否	结算时间
`payTime`	string(date-time)	否	支付时间
`closeTime`	string(date-time)	否	关闭时间
`expiredTime`	string(date-time)	否	过期时间
`attach`	string	否	商户扩展参数

常用取值

支付状态 status/orderStatus

value	说明
`wait`	待支付
`progress`	支付中
`success`	成功
`close`	支付关闭
`cancel`	支付撤销
`fail`	失败
`timeout`	支付超时

结算状态 settleStatus

value	说明
`not_settle`	未结算
`settled`	已结算

结算类型 settleType

value	说明
`REALTIME`	实时
`D+1`	D+1
`D+2`	D+2
`D+3`	D+3

成功响应示例

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "bizOrderNo": "BIZ-PAY-20260414-001",
    "orderNo": "P202604140001",
    "title": "Order Payment",
    "description": "Payment for order #001",
    "method": "mex_virtual_account",
    "limitPay": "string",
    "amount": 12.5,
    "fee": 0.01,
    "realAmount": 0.01,
    "status": "success",
    "settleStatus": "not_settle",
    "settleType": "D+1",
    "settleTime": "2026-04-14 12:00:00",
    "payTime": "2026-04-14 12:00:00",
    "closeTime": "2026-04-14 12:00:00",
    "expiredTime": "2026-04-14 12:00:00",
    "attach": "{\"orderTag\":\"vip\"}"
  },
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

失败响应示例

json

{
  "code": 20052,
  "msg": "验签失败",
  "data": null,
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

转账订单查询接口

查询转账订单当前状态和明细。

转账结果不确定、回调未收到或需要对账时调用。

请求信息

字段	说明
方法	POST
路径	`/unipay/query/transferOrder`
Content-Type	`application/json`

公共请求参数

字段	类型	必填	约束	说明
`mchNo`	string	是	maxLength=32	商户号
`appId`	string	否	maxLength=32	应用号
`reqTime`	string(date-time)	是	yyyy-MM-dd HH:mm:ss	请求时间, 格式yyyy-MM-dd HH:mm:ss
`nonceStr`	string	否	maxLength=32	随机数
`sign`	string	是	maxLength=1024	签名
`clientIp`	string	否	maxLength=64	客户端ip

业务参数

字段	类型	必填	约束	说明
`bizTransferNo`	string	否	maxLength=100	商户转账号
`transferNo`	string	否	maxLength=32	转账号

请求示例

json

{
  "clientIp": "127.0.0.1",
  "nonceStr": "nonce-20260414-001",
  "sign": "<BASE64_RSA_SIGNATURE>",
  "reqTime": "2026-04-14 12:00:00",
  "mchNo": "M2026000001",
  "appId": "APP20260001",
  "bizTransferNo": "BIZ-TRANSFER-20260414-001",
  "transferNo": "T202604140001"
}

响应 data 字段

字段	类型	必填	说明
`bizTransferNo`	string	否	商户转账号
`transferNo`	string	否	转账号
`amount`	number(double)	否	转账金额
`fee`	number(double)	否	手续费
`title`	string	否	标题
`reason`	string	否	转账原因/备注
`payeeType`	string	否	收款人类型
`payeeAccount`	string	否	收款人账号
`payeeName`	string	否	收款人姓名
`payeeCode`	string	否	收款编码(如银行代码)
`status`	string	否	状态
`finishTime`	string(date-time)	否	完成时间
`attach`	string	否	商户扩展参数

常用取值

收款类型 payeeType

value	说明
`user_id`	用户 ID
`open_id`	OpenId
`login_name`	用户账号
`bank_card`	银行卡
`spei_transfer`	SPEI 转账

转账状态 status/orderStatus

value	说明
`progress`	转账中
`success`	转账成功
`close`	转账关闭
`fail`	转账失败

成功响应示例

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "bizTransferNo": "BIZ-TRANSFER-20260414-001",
    "transferNo": "T202604140001",
    "amount": 12.5,
    "fee": 0.01,
    "title": "Order Payment",
    "reason": "Manual operation remark",
    "payeeType": "spei_transfer",
    "payeeAccount": "6222020202020202",
    "payeeName": "ZHANG SAN",
    "payeeCode": "mx_banxico",
    "status": "success",
    "finishTime": "2026-04-14 12:00:00",
    "attach": "{\"orderTag\":\"vip\"}"
  },
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

失败响应示例

json

{
  "code": 20052,
  "msg": "验签失败",
  "data": null,
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

支付订单同步接口

主动向上游同步支付订单状态并调整本地订单。

适用于回调延迟、状态长时间处于处理中或运营手动补偿。

请求信息

字段	说明
方法	POST
路径	`/unipay/sync/order/pay`
Content-Type	`application/json`

公共请求参数

字段	类型	必填	约束	说明
`mchNo`	string	是	maxLength=32	商户号
`appId`	string	否	maxLength=32	应用号
`reqTime`	string(date-time)	是	yyyy-MM-dd HH:mm:ss	请求时间, 格式yyyy-MM-dd HH:mm:ss
`nonceStr`	string	否	maxLength=32	随机数
`sign`	string	是	maxLength=1024	签名
`clientIp`	string	否	maxLength=64	客户端ip

业务参数

字段	类型	必填	约束	说明
`orderNo`	string	否	maxLength=100	订单号
`bizOrderNo`	string	否	maxLength=100	商户订单号

请求示例

json

{
  "clientIp": "127.0.0.1",
  "nonceStr": "nonce-20260414-001",
  "sign": "<BASE64_RSA_SIGNATURE>",
  "reqTime": "2026-04-14 12:00:00",
  "mchNo": "M2026000001",
  "appId": "APP20260001",
  "orderNo": "P202604140001",
  "bizOrderNo": "BIZ-PAY-20260414-001"
}

响应 data 字段

字段	类型	必填	说明
`orderStatus`	string	否	同步状态
`adjust`	boolean	否	是否触发了调整

常用取值

支付状态 status/orderStatus

value	说明
`wait`	待支付
`progress`	支付中
`success`	成功
`close`	支付关闭
`cancel`	支付撤销
`fail`	失败
`timeout`	支付超时

成功响应示例

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "orderStatus": "success",
    "adjust": true
  },
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

失败响应示例

json

{
  "code": 20052,
  "msg": "验签失败",
  "data": null,
  "sign": "<BASE64_RSA_SIGNATURE>",
  "resTime": "2026-04-14 12:00:01",
  "traceId": "f8e44de6f6a1467bb9cbf9be92f0ff3a"
}

YAML 下载

unipay-agent.yaml

Unipay 代理商户 API ​

概览 ​

商户模型 ​

响应信封 ​

接口列表 ​

支付接口 ​

请求信息 ​

公共请求参数 ​

业务参数 ​

请求示例 ​

响应 data 字段 ​

常用取值 ​

支付方式 method ​

限制支付 limitPay ​

支付状态 status/orderStatus ​

成功响应示例 ​

失败响应示例 ​

Callback 回调通知 ​

支付订单回调 ​

商户响应 ​

查询支付 method 列表 ​

请求信息 ​

公共请求参数 ​

业务参数 ​

请求示例 ​

响应 data 字段 ​

成功响应示例 ​

失败响应示例 ​

查询转账 payeeType 列表 ​

请求信息 ​

公共请求参数 ​

业务参数 ​

请求示例 ​

响应 data 字段 ​

成功响应示例 ​

失败响应示例 ​

查询转账 payeeCode 列表 ​

请求信息 ​

公共请求参数 ​

业务参数 ​

请求示例 ​

响应 data 字段 ​

成功响应示例 ​

失败响应示例 ​

关闭和撤销接口 ​

请求信息 ​

公共请求参数 ​

业务参数 ​

请求示例 ​

响应 data 字段 ​

成功响应示例 ​

失败响应示例 ​

转账预查询接口 ​

请求信息 ​

公共请求参数 ​

业务参数 ​

请求示例 ​

响应 data 字段 ​

常用取值 ​

收款类型 payeeType ​

预查询状态 status ​

成功响应示例 ​

失败响应示例 ​

转账接口 ​

请求信息 ​

公共请求参数 ​

业务参数 ​

请求示例 ​

响应 data 字段 ​

常用取值 ​

收款类型 payeeType ​

转账状态 status/orderStatus ​

成功响应示例 ​

失败响应示例 ​

Callback 回调通知 ​

转账订单回调 ​

商户响应 ​

支付订单查询接口 ​

请求信息 ​

公共请求参数 ​

Unipay 代理商户 API

概览

商户模型

响应信封

接口列表

支付接口

请求信息

公共请求参数

业务参数

请求示例

响应 data 字段

常用取值

支付方式 method

限制支付 limitPay

支付状态 status/orderStatus

成功响应示例

失败响应示例

Callback 回调通知

支付订单回调

商户响应

查询支付 method 列表

请求信息

公共请求参数

业务参数

请求示例

响应 data 字段

成功响应示例

失败响应示例

查询转账 payeeType 列表

请求信息

公共请求参数

业务参数

请求示例

响应 data 字段

成功响应示例

失败响应示例

查询转账 payeeCode 列表

请求信息

公共请求参数

业务参数

请求示例

响应 data 字段

成功响应示例

失败响应示例

关闭和撤销接口

请求信息

公共请求参数

业务参数

请求示例

响应 data 字段

成功响应示例

失败响应示例

转账预查询接口

请求信息

公共请求参数

业务参数

请求示例

响应 data 字段

常用取值

收款类型 payeeType

预查询状态 status

成功响应示例

失败响应示例

转账接口

请求信息

公共请求参数

业务参数

请求示例

响应 data 字段

常用取值

收款类型 payeeType

转账状态 status/orderStatus

成功响应示例

失败响应示例

Callback 回调通知

转账订单回调

商户响应

支付订单查询接口

请求信息

公共请求参数