支付网关接口文档

一、协议规则

传输方式：采用HTTP传输(生产环境建议HTTPS)
提交方式：POST 或 GET
内容类型：application/json
字符编码：UTF-8
签名算法：MD5

二、参数规范

交易金额：默认为人民币交易，单位为分，参数值不能带小数。
时间参数：所有涉及时间参数均使用精确到毫秒的13位数值，如：1622016572190。时间戳具体是指从格林尼治时间1970年01月01日00时00分00秒起至现在的毫秒数。

三、签名算法

1. 签名生成的通用步骤

第一步：拼接字符串 stringA

设所有发送或者接收到的数据为集合M，将集合M内非空参数值的参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA。

特别注意以下重要规则：

参数名ASCII码从小到大排序（字典序）；
如果参数的值为空不参与签名；
参数名区分大小写；
验证调用返回或支付中心主动通知签名时，传送的sign参数不参与签名，将生成的签名与该sign值作校验；
支付中心接口可能增加字段，验证签名时必须支持增加的扩展字段。

第二步：生成签名值 signValue

在stringA最后拼接上key[即 StringA +"&key=" + 私钥 ] 得到stringSignTemp字符串，并对stringSignTemp进行MD5运算，再将得到的字符串所有字符转换为大写，得到sign值signValue。

2. 签名示例

请求参数（Java示例）

Map<String, Object> paramsMap = new HashMap<>();
paramsMap.put("mchNo", "M1682391685");                   // 商户号
paramsMap.put("appId", "6447428682ca7458118af79f");      // 应用ID
paramsMap.put("mchOrderNo", "mho1694051705945");         // 商户订单号
paramsMap.put("wayCode", "ALI_BAR");                     // 支付方式
paramsMap.put("amount", 1L);                             // 金额，单位分
paramsMap.put("currency", "CNY");                        // 币种，目前只支持cny
paramsMap.put("clientIp", "192.166.1.132");              // 发起支付请求客户端的IP地址
paramsMap.put("subject", "商品标题");                     // 商品标题
paramsMap.put("body", "商品描述");                        // 商品描述
paramsMap.put("notifyUrl", "https://www.baidu.com");   // 异步通知地址
paramsMap.put("reqTime", "1694051706");                  // 请求时间
paramsMap.put("version", "1.0");                         // 接口版本号，固定：1.0
paramsMap.put("signType", "MD5");                        // 签名类型
paramsMap.put("channelExtra", "{\"authCode\":\"284957415846666792\"}");  // 渠道参数

待签名值

amount=1&appId=6447428682ca7458118af79f&body=商品描述&channelExtra={"authCode":"284957415846666792"}&clientIp=192.166.1.132¤cy=CNY&mchNo=M1682391685&mchOrderNo=mho1694051705945¬ifyUrl=https://www.baidu.com&reqTime=1694051706&signType=MD5&subject=商品标题&version=1.0&wayCode=ALI_BAR&key=UNpEETkvMpqC9oDLBr9S2X7U92k462h3zhHiy7hj4xbw23PiWhMv6TCAQ2vh8PzynZXZYo9n6puxHkAHG7li6LZi8IpaQrshzydnBll64iKlb4U59ggiyCTaHJeqffiW

签名结果

924065BA077FA461A9B06D2E76E9ED3C

最终请求支付系统参数

{
"amount":1,
"mchOrderNo":"mho1694051705945",
"subject":"商品标题",
"wayCode":"ALI_BAR",
"sign":"924065BA077FA461A9B06D2E76E9ED3C",
"reqTime":"1694051706",
"body":"商品描述",
"version":"1.0",
"channelExtra":"{\"authCode\":\"284957415846666792\"}",
"appId":"6447428682ca7458118af79f",
"clientIp":"192.166.1.132",
"notifyUrl":"https://www.baidu.com",
"signType":"MD5",
"currency":"CNY",
"mchNo":"M1682391685"
}

支付接口总览

以下为支付网关核心支付相关接口，包含统一下单、订单查询、订单关闭等功能接口说明。

一、支付接口（统一下单）

商户业务系统通过统一下单接口发起支付收款订单，支付网关会根据商户配置的支付通道路由支付通道完成支付下单。支付网关根据不同的支付方式返回对应的支付参数，业务系统使用支付参数发起收款。

1. 接口信息

适用对象：普通商户、特约商户
请求 URL：https://pay.xyzgpay.com/api/pay/unifiedOrder
请求方式：POST
请求类型：application/json 或 application/x-www-form-urlencoded

2. 请求参数

字段名	变量名	必填	类型	示例值	描述
商户号	`mchNo`	是	String(64)	M1621873433953	商户号
应用ID	`appId`	是	String(64)	60cc09bce4b0f1c0b83761c9	应用ID
商户订单号	`mchOrderNo`	是	String(64)	20160427210604000490	商户生成的订单号
支付方式	`wayCode`	是	String(20)	WX_LITE	支付方式,如微信小程序WX_LITE
支付金额	`amount`	是	int	100	支付金额,单位分
货币代码	`currency`	是	String(3)	cny	三位货币代码,人民币:cny
客户端IP	`clientIp`	否	String(128)	210.73.10.148	客户端IPV4地址
商品标题	`subject`	是	String(128)	商品标题测试	商品标题
商品描述	`body`	是	String(256)	商品描述测试	商品描述
门店编号	`storeId`	否	int	10010	商户的门店ID
码牌ID	`qrcId`	否	long	10010432445333	商户的码牌ID
终端设备信息	`deviceInfo`	否	String(256)	{"deviceType":"auto_pos","deviceNo":"abcde12345"}	智能POS、收银插件下单必填，json格式字符串，详见终端设备信息说明
异步通知地址	`notifyUrl`	否	String(256)	https://www.baidu.com/notify.htm	支付结果异步回调URL,只有传了该值才会发起回调
跳转通知地址	`returnUrl`	否	String(256)	https://www.baidu.com/return.htm	支付结果同步跳转通知URL
失效时间	`expiredTime`	否	int	3600	订单失效时间,单位秒,默认2小时.订单在(创建时间+失效时间)后失效
渠道参数	`channelExtra`	否	String(512)	{"auth_code":"13920933111042"}	特定渠道发起的额外参数,json格式字符串.详见渠道参数说明
分账模式	`divisionMode`	否	int	0	分账模式：0-该笔订单不允许分账[默认],1-支付成功按配置自动完成分账支付完成自动分账【需包含自动分账接收方，否则自动更新为0（V3.0.0新增）】,2-商户手动分账(解冻商户金额)
扩展参数	`extParam`	否	String(512)	134586944573118714	商户扩展参数,回调时会原样返回
请求时间	`reqTime`	是	long	1622016572190	请求接口时间,13位时间戳
接口版本	`version`	是	String(3)	1.0	接口版本号，固定：1.0
签名	`sign`	是	String(32)	C380BEC2BFD727A4B6845133519F3AD6	签名值，详见签名算法
签名类型	`signType`	是	String(32)	MD5	签名类型，目前只支持MD5或RSA2方式
合单支付子单列表	`subOrders`	否	String	[{"subMchid":"1746901131","outTradeNo":"sub1624005107","description":"测试商品1","amount":1},{"subMchid":"1746904745","outTradeNo":"sub21624005107","description":"测试商品2","amount":2}]	合单支付场景下的子单列表，json格式字符串。每项子单字段见下方说明
subOrders 数组中的子单字段：
二级商户号	`subMchid`	是	String(64)	1746901131	合单支付对应的二级商户号
子商户订单号	`outTradeNo`	是	String(64)	sub1624005107	二级商户生成的订单号，合单内不可重复
子单商品描述	`description`	是	String(256)	测试商品1	子单商品/订单描述
子单支付金额	`amount`	是	int	1	子单支付金额，单位分。所有子单金额之和需等于主单amount

3. 终端设备信息说明

字段名	变量名	必填	类型	示例值	描述
设备类型	`deviceType`	是	String(20)	auto_pos	智能POS：auto_pos，收银插件：cash_plugin
设备号	`deviceNo`	是	String(128)	abcde12345	设备号必填。设备类型为收银插件时传激活码；其他传设备号
设备厂商	`provider`	否	String(20)	abc	除智能POS外的其他设备类型，设备厂商必填

4. 请求示例数据

{
  "amount": 8,
  "extParam": "",
  "mchOrderNo": "mho1624005107281",
  "subject": "商品标题",
  "wayCode": "ALI_BAR",
  "sign": "84F606FA25A6EC4783BECC08D4FDC681",
  "reqTime": "1624005107",
  "body": "商品描述",
  "version": "1.0",
  "channelExtra": "{\"authCode\":\"280812820366966512\"}",
  "appId": "60cc09bce4b0f1c0b83761c9",
  "clientIp": "192.166.1.132",
  "notifyUrl": "https://www.baidu.com",
  "signType": "MD5",
  "currency": "cny",
  "returnUrl": "",
  "mchNo": "M1623984572",
  "divisionMode": 1,
  "subOrders": "[{\"subMchid\":\"1746901131\",\"outTradeNo\":\"sub1624005107\",\"description\":\"测试商品1\",\"amount\":1},{\"subMchid\":\"1746904745\",\"outTradeNo\":\"sub21624005107\",\"description\":\"测试商品2\",\"amount\":2}]"
}

5. 返回参数

字段名	变量名	必填	类型	示例值	描述
返回状态	`code`	是	int	0	0-处理成功，其他-处理有误，详见错误码
返回信息	`msg`	否	String(128)	签名失败	具体错误原因，例如：签名失败、参数格式校验错误
签名信息	`sign`	否	String(32)	CCD9083A6DAD9A2DA9F668C3D4517A84	对data内数据签名,如data为空则不返回
返回数据	`data`	否	String(512)	{}	返回下单数据,json格式数据

6. data数据格式

字段名	变量名	必填	类型	示例值	描述
支付订单号	`payOrderId`	是	String(30)	U12021022311124442600	返回支付系统订单号
商户订单号	`mchOrderNo`	是	String(30)	20160427210604000490	返回商户传入的订单号
订单状态	`orderState`	是	int	2	支付订单状态 0-订单生成 1-支付中 2-支付成功 3-支付失败 4-已撤销 5-已退款 6-订单关闭
支付数据类型	`payDataType`	是	String	payUrl	支付参数类型 payUrl-跳转链接的方式 form-表单方式 wxapp-微信支付参数(微信公众号,小程序,app支付时) aliapp-支付宝app支付参数 ysfapp-云闪付app支付参数 codeUrl-二维码地址 codeImgUrl-二维码图片地址 none-空支付参数
支付数据	`payData`	否	String	http://www.baidu.com/pay.html	发起支付用到的支付参数，如微信公众号和小程序发起支付使用的参数等
订单信息数据	`payOrderInfo`	否	String	{}	订单信息，当直接支付成功时会返回此数据
渠道错误码	`errCode`	否	String	ACQ.PAYMENT_AUTH_CODE_INVALID	上游渠道返回的错误码
渠道错误描述	`errMsg`	否	String	Business Failed 失败	上游渠道返回的错误描述

7. 返回示例数据

{
  "code": 0,
  "data": {
    "errCode": "ACQ.PAYMENT_AUTH_CODE_INVALID",
    "errMsg": "Business Failed【支付失败，获取顾客账户信息失败，请顾客刷新付款码后重新收款，如再次收款失败，请联系管理员处理。[SOUNDWAVE_PARSER_FAIL]】",
    "mchOrderNo": "mho1624005752661",
    "orderState": 3,
    "payOrderId": "P202106181642329900002"
  },
  "msg": "SUCCESS",
  "sign": "F4DA202C516D1F33A12F1E547C5004FD"
}

8. 支付方式

WayCode	支付方式
WEB_CASHIER	WEB收银台
QR_CASHIER	聚合扫码(用户扫商家)
WX_LITE_CASHIER	微信小程序收银台（浏览器唤起微信）
AUTO_BAR	聚合条码(商家扫用户)
ALI_BAR	支付宝条码
ALI_JSAPI	支付宝生活号
ALI_LITE	支付宝小程序
ALI_APP	支付宝APP
ALI_WAP	支付宝WAP
ALI_PC	支付宝PC网站
ALI_QR	支付宝二维码
WX_BAR	微信条码
WX_JSAPI	微信公众号
WX_LITE	微信小程序
WX_APP	微信APP
WX_H5	微信H5
WX_NATIVE	微信扫码
YSF_BAR	云闪付条码
YSF_JSAPI	云闪付jsapi
AUTO_POS	智能POS
DCEP_BAR	数字人民币条码
DCEP_QR	数字人民币二维码

9. channelExtra参数说明

当 wayCode=AUTO_BAR 或 wayCode=ALI_BAR 或 wayCode=WX_BAR 或 wayCode=YSF_BAR 时，channelExtra必须传auth_code，为用户的付款码值，channelExtra示例数据如：
{"authCode": "13920933111042"}
当 wayCode=ALI_JSAPI或 wayCode=ALI_LITE 时，channelExtra必须传buyerUserId，为支付宝用户ID，channelExtra示例数据如：
{"buyerUserId": "2088702585070844"}
当 wayCode=WX_JSAPI 或 wayCode=WX_LITE 时，channelExtra必须传openid，为微信OpenId， channelExtra示例数据如：
{"openid": "o6BcIwvSiRpfS8e_UyfQNrYuk2LI"}
注意： 若当前为特约商户，并且商户使用的自己的公众号或者小程序获取到的openId时：
需要：
1. 商户自己的公众号或者小程序的AppId需要在服务商里进行关联，请联系运营平台进行配置；
2. channelExtra参数中添加 subAppId 参数，该参数为商户的公众号或小程序的AppId，示例：
{ "openid": "o6BcIwvSiRpfS8e_UyfQNrYuk2LI", "subAppId":"wx08b5a41f7a27abf1" }
当 wayCode=ALI_QR 或 wayCode=WX_NATIVE 时，channelExtra可以传payDataType设置返回支付数据支付类型。此时payDataType可以为：codeUrl-二维码地址,codeImgUrl-二维码图片地址，不传payDataType默认返回codeUrl类型, channelExtra示例数据如：
{"payDataType": "codeImgUrl"}
当 wayCode=QR_CASHIER 时，channelExtra可以传payDataType、entryPageType和alipayWayCode。
entryPageType指定聚合码扫码时进入H5或小程序页面，默认为H5页面。h5-h5页面，lite-小程序页面。
alipayWayCode指定支付宝H5收银台的支付方式，可选ALI_JSAPI、ALI_WAP，默认为ALI_WAP。使用ALI_WAP时无需获取支付宝用户ID。
使用ALI_WAP时，收银台二次下单返回本站临时启动地址，支付宝表单不会返回给前端。
payDataType设置返回支付数据支付类型，此时payDataType可以为：codeUrl-二维码地址,codeImgUrl-二维码图片地址，不传payDataType默认返回codeUrl类型, channelExtra示例数据如：
{"entryPageType": "h5", "payDataType": "codeImgUrl", "alipayWayCode": "ALI_WAP"}
当 wayCode=WX_LITE_CASHIER 时，无需传channelExtra。接口固定返回 payDataType=payurl，payData为微信URL Scheme：
weixin://dl/business/?t=TICKET
浏览器包装页地址为 /cashier/pages/scheme/index?scheme=<URL编码后的Scheme>，用于自动尝试唤醒微信并提供用户点击按钮作为兼容入口。
当 wayCode=ALI_WAP 时，channelExtra可以传payDataType设置返回支付数据支付类型。此时payDataType可以为：form-返回自动跳转的支付表单,codeImgUrl-返回一个二维码图片URL,payUrl-返回支付链接，不传payDataType默认返回payUrl类型, channelExtra示例数据如：
{"payDataType": "form"}
当 wayCode=ALI_PC 时，channelExtra可以传payDataType设置返回支付数据支付类型。此时payDataType可以为：form-返回自动跳转的支付表单,payUrl-返回支付链接，不传payDataType默认返回payUrl类型, channelExtra示例数据如：
{"payDataType": "form"}

二、查询订单

商户通过该接口查询订单，支付网关会返回订单最新的数据

1. 接口说明

适用对象：普通商户、特约商户
请求 URL：https://pay.xyzgpay.com/api/pay/query
请求方式：POST
请求类型：application/json 或 application/x-www-form-urlencoded

2. 请求参数

字段名	变量名	必填	类型	示例值	描述
商户号	`mchNo`	是	String(64)	M1621873433953	商户号
应用ID	`appId`	是	String(64)	60cc09bce4b0f1c0b83761c9	应用ID
支付订单号	`payOrderId`	是	String(30)	P20160427210604000490	支付中心生成的订单号，与mchOrderNo二者传一即可
商户订单号	`mchOrderNo`	是	String(64)	20160427210604000490	商户生成的订单号，与payOrderId二者传一即可
请求时间	`reqTime`	是	long	1622016572190	请求接口时间,13位时间戳
接口版本	`version`	是	String(3)	1.0	接口版本号，固定：1.0
签名	`sign`	是	String(32)	C380BEC2BFD727A4B6845133519F3AD6	签名值，详见签名算法
签名类型	`signType`	是	String(32)	MD5	签名类型，目前只支持MD5或RSA2方式

3. 请求示例数据

{
  "payOrderId": "P202106181104177050002",
  "appId": "60cc09bce4b0f1c0b83761c9",
  "sign": "46940C58B2F3AE426B77A297ABF4D31E",
  "signType": "MD5",
  "reqTime": "1624006009",
  "mchNo": "M1623984572",
  "version": "1.0"
}

4. 返回参数

字段名	变量名	必填	类型	示例值	描述
返回状态	`code`	是	int	0	0-处理成功，其他-处理有误，详见错误码
返回信息	`msg`	否	String(128)	签名失败	具体错误原因，例如：签名失败、参数格式校验错误
签名信息	`sign`	否	String(32)	CCD9083A6DAD9A2DA9F668C3D4517A84	对data内数据签名,如data为空则不返回
返回数据	`data`	否	String(512)	{}	返回下单数据,json格式数据

5. data数据格式

字段名	变量名	必填	类型	示例值	描述
支付订单号	`payOrderId`	是	String(30)	P12021022311124442600	返回支付系统订单号
商户号	`mchNo`	是	String(30)	M1621873433953	商户号
应用ID	`appId`	是	String(24)	60cc09bce4b0f1c0b83761c9	应用ID
商户订单号	`mchOrderNo`	是	String(30)	20160427210604000490	返回商户传入的订单号
支付接口	`ifCode`	是	String(30)	wxpay	支付接口编码
支付方式	`wayCode`	是	String(30)	WX_LITE	支付方式,如微信小程序WX_LITE
支付金额	`amount`	是	int	100	支付金额,单位分
货币代码	`currency`	是	String(3)	cny	三位货币代码,人民币:cny
订单状态	`state`	是	int	2	支付订单状态 0-订单生成 1-支付中 2-支付成功 3-支付失败 4-已撤销 5-已退款 6-订单关闭
客户端IP	`clientIp`	否	String(32)	210.73.10.148	客户端IPV4地址
商品标题	`subject`	是	String(128)	商品标题测试	商品标题
商品描述	`body`	是	String(256)	商品描述测试	商品描述
渠道订单号	`channelOrderNo`	否	String	20160427210604000490	对应渠道的订单号
渠道错误码	`errCode`	否	String	1002	渠道下单返回错误码
渠道错误描述	`errMsg`	否	String	134586944573118714	渠道下单返回错误描述
扩展参数	`extParam`	否	String(512)	134586944573118714	商户扩展参数,回调时会原样返回
创建时间	`createdAt`	是	long	1622016572190	订单创建时间,13位时间戳
成功时间	`successTime`	否	long	1622016572190	订单支付成功时间,13位时间戳

6. 返回示例数据

{
  "code": 0,
  "data": {
    "amount": 58,
    "appId": "60cc09bce4b0f1c0b83761c9",
    "body": "商品描述",
    "channelOrderNo": "2021061822001423031419593035",
    "clientIp": "192.166.1.132",
    "createdAt": 1623985457705,
    "currency": "cny",
    "extParam": "",
    "ifCode": "alipay",
    "mchNo": "M1623984572",
    "mchOrderNo": "mho1623985457320",
    "payOrderId": "P202106181104177050002",
    "state": 2,
    "subject": "商品标题",
    "successTime": 1623985459000,
    "wayCode": "ALI_BAR"
  },
  "msg": "SUCCESS",
  "sign": "9548145EA12D0CD8C1628BCF44E19E0D"
}

三、关闭订单

商户通过该接口关闭订单，支付网关会对订单完成关闭处理。

1. 接口说明

适用对象：普通商户、特约商户
请求 URL：https://pay.xyzgpay.com/api/pay/close
请求方式：POST
请求类型：application/json 或 application/x-www-form-urlencoded

2. 请求参数

字段名	变量名	必填	类型	示例值	描述
商户号	`mchNo`	是	String(64)	M1621873433953	商户号
应用ID	`appId`	是	String(64)	60cc09bce4b0f1c0b83761c9	应用ID
支付订单号	`payOrderId`	是	String(30)	P20160427210604000490	支付中心生成的订单号，与mchOrderNo二者传一即可
商户订单号	`mchOrderNo`	是	String(64)	20160427210604000490	商户生成的订单号，与payOrderId二者传一即可
请求时间	`reqTime`	是	long	1622016572190	请求接口时间,13位时间戳
接口版本	`version`	是	String(3)	1.0	接口版本号，固定：1.0
签名	`sign`	是	String(32)	C380BEC2BFD727A4B6845133519F3AD6	签名值，详见签名算法
签名类型	`signType`	是	String(32)	MD5	签名类型，目前只支持MD5或RSA2方式

3. 请求示例数据

{
  "payOrderId": "P202106181104177050002",
  "appId": "60cc09bce4b0f1c0b83761c9",
  "sign": "46940C58B2F3AE426B77A297ABF4D31E",
  "signType": "MD5",
  "reqTime": "1624006009",
  "mchNo": "M1623984572",
  "version": "1.0"
}

4. 返回参数

字段名	变量名	必填	类型	示例值	描述
返回状态	`code`	是	int	0	0-处理成功，其他-处理有误，详见错误码
返回信息	`msg`	否	String(128)	签名失败	具体错误原因，例如：签名失败、参数格式校验错误
签名信息	`sign`	否	String(32)	CCD9083A6DAD9A2DA9F668C3D4517A84	对data内数据签名,如data为空则不返回
返回数据	`data`	否	String(512)	{}	返回下单数据,json格式数据

5. data数据格式

字段名	变量名	必填	类型	示例值	描述
渠道错误码	`errCode`	否	String	1002	渠道关单返回错误码
渠道错误描述	`errMsg`	否	String	关闭异常	渠道关单返回错误描述

6. 返回示例数据

{
  "code": 0,
  "data": {
    "errCode": "",
    "errMsg": ""
  },
  "msg": "SUCCESS",
  "sign": "9548145EA12D0CD8C1628BCF44E19E0D"
}

四、条码换取openId

商户通过该接口上送刷卡条码值，换取到微信openId。

1. 接口说明

适用对象：普通商户、特约商户
请求 URL：https://pay.xyzgpay.com/api/pay/queryOpenIdByBarcode
请求方式：POST
请求类型：application/json 或 application/x-www-form-urlencoded

2. 请求参数

字段名	变量名	必填	类型	示例值	描述
商户号	`mchNo`	是	String(64)	M1621873433953	商户号
应用ID	`appId`	是	String(64)	60cc09bce4b0f1c0b83761c9	应用ID
条码数据	`barCode`	是	String(60)	20160427210604000490	条码值
子应用ID	`subAppId`	否	String(30)	20160427210604000490	若传入则透传到三方支付
请求时间	`reqTime`	是	long	1622016572190	请求接口时间,13位时间戳
接口版本	`version`	是	String(3)	1.0	接口版本号，固定：1.0
签名	`sign`	是	String(32)	C380BEC2BFD727A4B6845133519F3AD6	签名值，详见签名算法
签名类型	`signType`	是	String(32)	MD5	签名类型，目前只支持MD5或RSA2方式

3. 请求示例数据

{
  "barCode": "202106181104177050002",
  "sign": "46940C58B2F3AE426B77A297ABF4D31E",
  "signType": "MD5",
  "reqTime": "1624006009",
  "mchNo": "M1623984572",
  "version": "1.0"
}

4. 返回参数

字段名	变量名	必填	类型	示例值	描述
返回状态	`code`	是	int	0	0-处理成功，其他-处理有误，详见错误码
返回信息	`msg`	否	String(128)	签名失败	具体错误原因，例如：签名失败、参数格式校验错误
签名信息	`sign`	否	String(32)	CCD9083A6DAD9A2DA9F668C3D4517A84	对data内数据签名,如data为空则不返回
返回数据	`data`	否	String(512)	{}	返回下单数据,json格式数据

5. data数据格式

字段名	变量名	必填	类型	示例值	描述
开放ID	`openId`	否	String	1002	openId
子开放ID	`subOpenId`	否	String	1002	subOpenId

6. 返回示例数据

{
  "code": 0,
  "data": {
    "openId": "",
    "subOpenId": ""
  },
  "msg": "SUCCESS",
  "sign": "9548145EA12D0CD8C1628BCF44E19E0D"
}

五、支付通知

当订单支付成功时，支付网关会向商户系统发起回调通知。如果商户系统没有正确返回，支付网关会延迟再次通知。

1. 接口说明

适用对象：普通商户、特约商户
请求 URL：该链接是通过统一下单接口提交的参数notifyUrl设置，如果无法访问链接，商户系统将无法接收到支付中心的通知。
请求方式：POST
请求类型：application/x-www-form-urlencoded

2. 通知参数

字段名	变量名	必填	类型	示例值	描述
支付订单号	`payOrderId`	是	String(30)	P12021022311124442600	返回支付系统订单号
商户号	`mchNo`	是	String(30)	M1621873433953	商户号
应用ID	`appId`	是	String(24)	60cc09bce4b0f1c0b83761c9	应用ID
商户订单号	`mchOrderNo`	是	String(30)	20160427210604000490	返回商户传入的订单号
支付接口	`ifCode`	是	String(30)	wxpay	支付接口编码
支付方式	`wayCode`	是	String(30)	WX_LITE	支付方式,微信小程序WX_LITE
支付金额	`amount`	是	int	100	支付金额,单位分
货币代码	`currency`	是	String(3)	cny	三位货币代码,人民币:cny
订单状态	`state`	是	int	2	支付订单状态 0-订单生成 1-支付中 2-支付成功 3-支付失败 4-已撤销 5-已退款 6-订单关闭
客户端IP	`clientIp`	否	String(32)	210.73.10.148	客户端IPV4地址
商品标题	`subject`	是	String(128)	商品标题测试	商品标题
商品描述	`body`	是	String(256)	商品描述测试	商品描述
渠道订单号	`channelOrderNo`	否	String	20160427210604000490	对应渠道的订单号
渠道错误码	`errCode`	否	String	1002	渠道下单返回错误码
渠道错误描述	`errMsg`	否	String	134586944573118714	渠道下单返回错误描述
扩展参数	`extParam`	否	String(512)	134586944573118714	商户扩展参数
支付成功时间	`successTime`	否	long	1622016572190	订单支付成功时间,13位时间戳
创建时间	`createdAt`	是	long	1622016572190	订单创建时间,13位时间戳
通知请求时间	`reqTime`	是	String(30)	1622016572190	通知请求时间，13位时间戳
签名	`sign`	是	String(32)	C380BEC2BFD727A4B6845133519F3AD6	签名值，详见签名算法

3. 扩展参数（需商户后台配置）

字段名	变量名	必填	类型	示例值	描述
商户门店ID	`storeId`	否	int	-	商户门店ID
经度	`lng`	否	String	-	商户门店经度
纬度	`lat`	否	String	-	商户门店纬度
码牌ID	`qrcId`	否	int	-	商户码牌ID
支付方式代码分类	`wayCodeType`	否	String	-	支付方式代码分类
商户手续费费率	`mchFeeRate`	否	String	-	商户手续费费率
商户手续费	`mchFeeAmount`	否	int	-	商户手续费,单位分
渠道用户标识	`channelUser`	否	String	-	渠道用户标识,如微信openId,支付宝账号
订单分账模式	`divisionMode`	否	int	-	订单分账模式：0-该笔订单不允许分账, 1-支付成功按配置自动完成分账, 2-商户手动分账(解冻商户金额)
买家备注	`buyerRemark`	否	String	-	买家备注
卖家备注	`sellerRemark`	否	String	-	卖家备注
订单失效时间	`expiredTime`	否	long	-	订单失效时间
支付凭证交易单号	`platformOrderNo`	否	String	-	支付凭证交易单号
支付凭证商户单号	`platformMchOrderNo`	否	String	-	支付凭证商户单号

4. 返回结果

业务系统处理后同步返回给支付中心，返回字符串 success 则表示成功，返回非success则表示处理失败，支付中心会再次通知业务系统。（通知频率为0/30/60/90/120/150,单位：秒）

注意：返回的字符串不区分大小写，字符串前后不能有空格和换行符。

5. 通知示例数据

{
    "amount": 5,
    "body": "商品描述",
    "clientIp": "192.166.1.132",
    "createdAt": "1622016572190",
    "currency": "cny",
    "extParam": "",
    "ifCode": "wxpay",
    "mchNo": "M1621873433953",
    "appId": "60cc09bce4b0f1c0b83761c9",
    "mchOrderNo": "mho1621934803068",
    "payOrderId": "20210525172643357010",
    "state": 3,
    "subject": "商品标题",
    "wayCode": "WX_BAR",
    "sign": "C380BEC2BFD727A4B6845133519F3AD6"
}

六、获取渠道用户ID

商户通过该接口获取渠道的用户ID，如微信的openID，支付宝的userId。该接口通过跳转获取到用户ID后，会跳转到商户上传的redirectUrl地址，并传递用户ID参数

1. 接口信息

适用对象：普通商户、特约商户
请求 URL：https://pay.xyzgpay.com/api/channelUserId/jump
请求方式：GET
请求类型：application/json 或 application/x-www-form-urlencoded

2. 请求参数

字段名	变量名	必填	类型	示例值	描述
商户号	`mchNo`	是	String(30)	M1621873433953	商户号
应用ID	`appId`	是	String(24)	60cc09bce4b0f1c0b83761c9	应用ID
支付接口	`ifCode`	是	String(30)	AUTO	目前只支持传 AUTO
跳转地址	`redirectUrl`	是	String	https://www.baidu.com	获取到用户ID后，会携带用户ID参数跳转到该地址
请求时间	`reqTime`	是	long	1622016572190	请求接口时间,13位时间戳
接口版本	`version`	是	String(3)	1.0	接口版本号，固定：1.0
签名	`sign`	是	String(32)	C380BEC2BFD727A4B6845133519F3AD6	签名值，详见签名算法
签名类型	`signType`	是	String(32)	MD5	签名类型，目前只支持MD5或RSA2方式

3. 请求示例数据

{
  "mchNo": "M1621873433953",
  "appId": "60cc09bce4b0f1c0b83761c9",
  "ifCode": "wxpay",
  "redirectUrl": "https://www.baidu.com",
  "sign": "A5C93D50743126ED91AA6ED96CDEEEF8",
  "signType": "MD5",
  "reqTime": "1622011236571",
  "version": "1.0"
}

4. 跳转返回参数

当获取到渠道用户ID后，会301重定向到跳转地址，传递参数如下：

字段名	变量名	必填	类型	示例值	描述
渠道用户ID	`channelUserId`	是	String	o6BcIwvSiRpfS8e_UyfQNrYuk2LI	渠道用户ID，微信openId或支付宝userId

5. 完整跳转URL示例

https://www.baidu.com/toU?channelUserId=o6BcIwvSiRpfS8e_UyfQNrYuk2LI

七、返回码

code	描述
0	成功
9999	异常，具体错误详见msg字段

退款接口总览

以下为支付网关核心退款相关接口，包含统一退款、退款订单查询、退款通知等功能接口说明。

一、统一退款

商户业务系统通过统一退款接口发起退款请求，支付网关会根据商户发起的支付订单号，找到对应到支付通道发起退款。

1. 接口说明

适用对象：普通商户特约商户
请求URL：https://pay.xyzgpay.com/api/refund/refundOrder
请求方式：POST
请求类型：application/json 或 application/x-www-form-urlencoded

2. 请求参数

字段名	变量名	必填	类型	示例值	描述
商户号	`mchNo`	是	String(64)	M1621873433953	商户号
应用ID	`appId`	是	String(64)	60cc09bce4b0f1c0b83761c9	应用ID
支付订单号	`payOrderId`	是	String(30)	P20160427210604000490	支付中心生成的订单号，与mchOrderNo二者传一即可
商户订单号	`mchOrderNo`	是	String(64)	20160427210604000490	商户生成的支付订单号，与payOrderId二者传一即可
商户退款单号	`mchRefundNo`	是	String(64)	M27210632100491	商户生成的退款单号
退款金额	`refundAmount`	是	int	100	退款金额,单位分
货币代码	`currency`	是	String(3)	cny	三位货币代码,人民币:cny
退款原因	`refundReason`	是	String(256)	用户退货	退款原因
客户端IP	`clientIp`	否	String(128)	210.73.10.148	客户端IPV4地址
异步通知地址	`notifyUrl`	否	String(128)	https://www.baidu.com/notify.htm	退款完成后回调该URL,只有传了该值才会发起回调
渠道参数	`channelExtra`	否	String(512)	{"channel_ref", "13920933111042"}	特定渠道发起的额外参数,json格式字符串.详见渠道参数说明
扩展参数	`extParam`	否	String(512)	134586944573118714	商户扩展参数,回调时会原样返回
请求时间	`reqTime`	是	long	1622016572190	请求接口时间,13位时间戳
接口版本	`version`	是	String(3)	1.0	接口版本号，固定：1.0
签名	`sign`	是	String(32)	C380BEC2BFD727A4B6845133519F3AD6	签名值，详见签名算法
签名类型	`signType`	是	String(32)	MD5	签名类型，目前只支持MD5或RSA2方式

3. 请求示例数据

{
  "payOrderId": "P202106181104177050002",
  "extParam": "",
  "mchOrderNo": "",
  "refundReason": "退款测试",
  "sign": "2762CDB48D5179281DB6C0995E4EEDE0",
  "reqTime": "1624007315",
  "version": "1.0",
  "channelExtra": "",
  "appId": "60cc09bce4b0f1c0b83761c9",
  "mchRefundNo": "mho1624007315478",
  "clientIp": "192.166.1.132",
  "notifyUrl": "https://www.baidu.com",
  "signType": "MD5",
  "currency": "cny",
  "mchNo": "M1623984572",
  "refundAmount": 4
}

4. 返回参数

字段名	变量名	必填	类型	示例值	描述
返回状态	`code`	是	int	0	0-处理成功，其他-处理有误，详见错误码
返回信息	`msg`	否	String(128)	签名失败	具体错误原因，例如：签名失败、参数格式校验错误
签名信息	`sign`	否	String(32)	CCD9083A6DAD9A2DA9F668C3D4517A84	对data内数据签名,如data为空则不返回
返回数据	`data`	否	String(512)	{}	返回下单数据,json格式数据

5. data数据格式

字段名	变量名	必填	类型	示例值	描述
退款订单号	`refundOrderId`	是	String(30)	R202106181708358940000	返回退款订单号
商户退款单号	`mchRefundNo`	是	String(30)	mho1624007315478	返回商户传入的退款单号
退款状态	`state`	是	int	2	退款状态 0-订单生成 1-退款中 2-退款成功 3-退款失败 4-退款关闭
渠道退款单号	`channelOrderNo`	否	String	20160427210604000490	对应渠道的退款单号
渠道错误码	`errCode`	否	String	ACQ.PAYMENT_AUTH_CODE_INVALID	上游渠道返回的错误码
渠道错误描述	`errMsg`	否	String	Business Failed 失败	上游渠道返回的错误描述

6. 返回示例数据

{
  "code": 0,
  "data": {
    "channelOrderNo": "2021061822001423031419593035",
    "mchRefundNo": "mho1624007315478",
    "payAmount": 58,
    "refundAmount": 4,
    "refundOrderId": "R202106181708358940000",
    "state": 2
  },
  "msg": "SUCCESS",
  "sign": "2843B811B7A75D56B7D1950362820875"
}

二、查询退款订单

商户通过该接口查询退款订单，支付网关会返回订单最新的数据

1. 接口说明

适用对象：普通商户特约商户
请求URL：https://pay.xyzgpay.com/api/refund/query
请求方式：POST
请求类型：application/json 或 application/x-www-form-urlencoded

2. 请求参数

字段名	变量名	必填	类型	示例值	描述
商户号	`mchNo`	是	String(64)	M1621873433953	商户号
应用ID	`appId`	是	String(64)	60cc09bce4b0f1c0b83761c9	应用ID
退款订单号	`refundOrderId`	是	String(30)	R20160427210604000490	支付中心生成的退款单号，与mchRefundNo二者传一即可
商户退款单号	`mchRefundNo`	是	String(64)	20160427210604000490	商户生成的退款单号，与refundOrderId二者传一即可
请求时间	`reqTime`	是	long	1622016572190	请求接口时间,13位时间戳
接口版本	`version`	是	String(3)	1.0	接口版本号，固定：1.0
签名	`sign`	是	String(32)	C380BEC2BFD727A4B6845133519F3AD6	签名值，详见签名算法
签名类型	`signType`	是	String(32)	MD5	签名类型，目前只支持MD5或RSA2方式

3. 请求示例数据

{
  "refundOrderId": "P202106181105527690009",
  "appId": "60cc09bce4b0f1c0b83761c9",
  "sign": "1484293FCAEAFE11DEC8949DB6B525A9",
  "signType": "MD5",
  "reqTime": "1624008199",
  "mchNo": "M1623984572",
  "version": "1.0"
}

4. 返回参数

字段名	变量名	必填	类型	示例值	描述
返回状态	`code`	是	int	0	0-处理成功，其他-处理有误，详见错误码
返回信息	`msg`	否	String(128)	签名失败	具体错误原因，例如：签名失败、参数格式校验错误
签名信息	`sign`	否	String(32)	CCD9083A6DAD9A2DA9F668C3D4517A84	对data内数据签名,如data为空则不返回
返回数据	`data`	否	String(512)	{}	返回下单数据,json格式数据

5. data数据格式

字段名	变量名	必填	类型	示例值	描述
退款订单号	`refundOrderId`	是	String(30)	R20160427210604000490	支付中心生成的退款单号
支付订单号	`payOrderId`	是	String(30)	P12021022311124442600	返回支付系统订单号
商户号	`mchNo`	是	String(30)	M1621873433953	商户号
应用ID	`appId`	是	String(24)	60cc09bce4b0f1c0b83761c9	应用ID
商户退款单号	`mchRefundNo`	是	String(30)	20160427210604000490	商户退款单号
支付金额	`payAmount`	是	String(30)	100	支付金额,单位分
退款金额	`refundAmount`	是	String(30)	100	退款金额,单位分
货币代码	`currency`	是	String(30)	cny	三位货币代码,人民币:cny
退款状态	`state`	是	int	cny	退款状态:0-订单生成、1-退款中、2-退款成功、3-退款失败、4-退款关闭
渠道订单号	`channelOrderNo`	否	String	20160427210604000490	对应渠道的订单号
渠道错误码	`errCode`	否	String	1002	渠道返回错误码
渠道错误描述	`errMsg`	否	String	134586944573118714	渠道返回错误描述
扩展参数	`extParam`	否	String	134586944573118714	商户扩展参数,回调时会原样返回
创建时间	`createdAt`	是	long	1622016572190	订单创建时间,13位时间戳
成功时间	`successTime`	否	long	1622016572190	订单支付成功时间,13位时间戳

6. 返回示例数据

{
  "code": 0,
  "data": {
    "appId": "60cc09bce4b0f1c0b83761c9",
    "channelOrderNo": "2021061822001423031419593035",
    "createdAt": 1623985552769,
    "currency": "cny",
    "extParam": "",
    "mchNo": "M1623984572",
    "mchRefundNo": "mho1623985552430",
    "payAmount": 58,
    "payOrderId": "P202106181104177050002",
    "refundAmount": 4,
    "refundOrderId": "P202106181105527690009",
    "state": 2,
    "successTime": 1623985554000
  },
  "msg": "SUCCESS",
  "sign": "E3F9F008FC5EF84BD782CCC7BE69DC5E"
}

三、退款通知

当退款完成时(成功或失败)，支付网关会向商户系统发起回调通知。如果商户系统没有正确返回，支付网关会延迟再次通知。

1. 接口说明

适用对象：普通商户特约商户
请求URL：该链接是通过统一退款接口提交的参数notifyUrl设置，如果无法访问链接，商户系统将无法接收到支付中心的通知。
请求方式：POST
请求类型：application/x-www-form-urlencoded

2. 通知参数

字段名	变量名	必填	类型	示例值	描述
退款订单号	`refundOrderId`	是	String(30)	R20160427210604000490	支付中心生成的退款单号
支付订单号	`payOrderId`	是	String(30)	P12021022311124442600	返回支付系统订单号
商户号	`mchNo`	是	String(30)	M1621873433953	商户号
应用ID	`appId`	是	String(24)	60cc09bce4b0f1c0b83761c9	应用ID
商户退款单号	`mchRefundNo`	是	String(30)	20160427210604000490	商户生成的退款单号
支付金额	`payAmount`	是	int	100	支付金额,单位分
退款金额	`refundAmount`	是	int	100	退款金额,单位分
货币代码	`currency`	是	String(3)	cny	三位货币代码,人民币:cny
退款状态	`state`	是	int	2	退款状态：0-订单生成、1-退款中、2-退款成功、3-退款失败、4-退款关闭
渠道订单号	`channelOrderNo`	否	String	20160427210604000490	对应渠道的订单号
渠道错误码	`errCode`	否	String	1002	渠道返回错误码
渠道错误描述	`errMsg`	否	String	134586944573118714	渠道返回错误描述
扩展参数	`extParam`	否	String(512)	134586944573118714	商户扩展参数,回调时会原样返回
创建时间	`createdAt`	是	long	1622016572190	订单创建时间,13位时间戳
成功时间	`successTime`	否	long	1622016572190	订单支付成功时间,13位时间戳
通知请求时间	`reqTime`	是	String(30)	1622016572190	通知请求时间，13位时间戳
签名	`sign`	是	String(32)	C380BEC2BFD727A4B6845133519F3AD6	签名值，详见签名算法

3. 返回结果

业务系统处理后同步返回给支付中心，返回字符串 success 则表示成功，返回非success则表示处理失败，支付中心会再次通知业务系统。（通知频率为0/30/60/90/120/150,单位：秒）

注意：返回的字符串必须是小写，且前后不能有空格和换行符。

4. 通知示例数据

{
    "appId": "60cc09bce4b0f1c0b83761c9",
    "channelOrderNo": "2021061822001423031419593035",
    "createdAt": 1623985552769,
    "currency": "cny",
    "extParam": "",
    "mchNo": "M1623984572",
    "mchRefundNo": "mho1623985552430",
    "payAmount": 58,
    "payOrderId": "P202106181104177050002",
    "refundAmount": 4,
    "refundOrderId": "P202106181105527690009",
    "state": 2,
    "successTime": 1623985554000
}

转账接口总览(暂时关闭转账分账接口)

以下为支付网关核心转账相关接口，包含发起转账、转账订单查询、转账通知、查询转账可用余额等功能接口说明。

投诉接口总览

以下为支付网关核心投诉相关接口，包含订单投诉列表查询、订单投诉详情查询、投诉处理、投诉上传图片等功能接口说明。

接口列表

一、订单投诉列表 - 查询商户的订单投诉列表
二、订单投诉详情 - 查询订单投诉的详细信息
三、投诉处理 - 商户处理投诉（回复/反馈完成/处理投诉/退款进度更新）
四、投诉上传图片 - 商户上传投诉处理凭证图片
五、投诉回调接口 - 商户接收投诉通知回调

一、订单投诉列表

商户通过该接口查询订单投诉列表，支持按渠道、状态、时间范围等条件筛选。

1. 请求参数

字段名	参数名	必填	类型	示例值	描述
商户号	`mchNo`	是	String	M1778058637	商户号
应用ID	`appId`	是	String	69fb058daf98c3ede32f88c9	应用ID
请求时间	`reqTime`	是	String	1750137600	当前时间戳(秒)
版本号	`version`	是	String	1.0	接口版本号
签名类型	`signType`	是	String	MD5	签名类型(MD5/RSA)
签名	`sign`	是	String	C380BEC2BFD727A4B6845133519F3AD6	签名值
渠道	`ifCode`	否	String	wxpay	支付渠道代码
平台订单号	`payOrderId`	否	String		支付中心生成的订单号
渠道订单号	`channelOrderNo`	否	String		渠道侧订单号
查询时间范围	`queryDateRange`	否	String	customDate_2026-06-01_2026-06-02	时间范围：today(今天), yesterday(昨天), currMonth(本月), prevMonth(上月), customDate_yyyy-MM-dd_yyyy-MM-dd(自定义)
页码	`pageNumber`	否	String	1	页码，默认1
每页条数	`pageSize`	否	String	10	每页条数，默认10

2. 请求 URL

请求 URL：https://pay.xyzgpay.com/api/pay/complaint/list

3. 请求示例数据

{
    "mchNo": "M1778058637",
    "appId": "69fb058daf98c3ede32f88c9",
    "reqTime": "1750137600",
    "version": "1.0",
    "signType": "MD5",
    "ifCode": "",
    "state": "",
    "payOrderId": "",
    "channelOrderNo": "",
    "queryDateRange": "customDate_2026-06-01_2026-06-02",
    "pageNumber": "1",
    "pageSize": "10",
    "sign": "C380BEC2BFD727A4B6845133519F3AD6"
    }

4. 返回参数(解密方式，将data值转成map，然后进行验签)

字段名	参数名	必填	类型	示例值	描述
返回码	`code`	是	int	0	返回码，0表示成功
返回信息	`msg`	是	String	SUCCESS	返回信息
签名	`sign`	否	String	1B3F24D0076FBA2E7BB626C62E12F49D	签名值
页码	`pageNumber`	是	int	1	当前页码
每页条数	`pageSize`	是	int	10	每页条数
总数	`total`	是	int	4	投诉记录总数
投诉列表	`list`	是	Array		投诉记录列表
list 数组中的字段：
投诉单号	`complaintId`	是	String	21019634507	投诉单号
平台订单号	`payOrderId`	是	String	P2061765260164395010	支付中心生成的订单号
渠道订单号	`channelOrderNo`	是	String	2026060222001440631414795917	渠道侧订单号
商户号	`mchNo`	是	String	M1778058637	商户号
应用ID	`appId`	是	String	69fb058daf98c3ede32f88c9	应用ID
渠道代码	`ifCode`	是	String	zftpay	支付渠道代码
支付方式	`wayCode`	是	String	ALI_WAP	支付方式代码
订单金额	`amount`	是	long	18800	订单金额(单位：分)
币种	`currency`	是	String	cny	币种
投诉时间	`complaintTime`	是	String	2026-06-02 21:44:33	投诉时间
投诉截止时间	`complaintDeadline`	是	String	2026-06-05 21:46:07	投诉处理截止时间
投诉详情	`complaintDetail`	是	String	诱导赌博，属于赌博，举报举报。	投诉详情描述
投诉标签	`complaintTag`	否	String	升级投诉	投诉标签(如：升级投诉)
投诉状态	`state`	是	int	2	投诉状态：0-待处理，1-处理中，3-处理完成，4-已撤销
退款金额	`refundAmount`	是	long	0	已退款金额(单位：分)
退款状态	`refundState`	是	int	0	退款状态：0-未退款 1-已退款

5. 返回示例数据

{
    "code": 0,
    "msg": "SUCCESS",
    "data": {
        "pageNumber": 1,
        "pageSize": 10,
        "total": 4,
        "list": [
            {
                "amount": 18800,
                "appId": "69fb058daf98c3ede32f88c9",
                "channelOrderNo": "2026060222001440631414795917",
                "complaintDeadline": "2026-06-05 21:46:07",
                "complaintDetail": "诱导赌博，属于赌博，举报举报。",
                "complaintId": "21019634507",
                "complaintTag": "",
                "complaintTime": "2026-06-02 21:44:33",
                "currency": "cny",
                "ifCode": "zftpay",
                "mchNo": "M1778058637",
                "payOrderId": "P2061765260164395010",
                "refundAmount": 0,
                "refundState": 0,
                "state": 2,
                "wayCode": "ALI_WAP"
            },
            {
                "amount": 600,
                "appId": "69fb058daf98c3ede32f88c9",
                "channelOrderNo": "2026053123001463181440556516",
                "complaintDeadline": "2026-06-04 18:50:59",
                "complaintDetail": "充完值号就封了这个平台是诈骗能不能解决一下",
                "complaintId": "21014707774",
                "complaintTag": "",
                "complaintTime": "2026-06-01 18:48:10",
                "currency": "cny",
                "ifCode": "zftpay",
                "mchNo": "M1778058637",
                "payOrderId": "P2061013856718102530",
                "refundAmount": 0,
                "refundState": 0,
                "state": 2,
                "wayCode": "ALI_WAP"
            },
            {
                "amount": 9900,
                "appId": "69fb058daf98c3ede32f88c9",
                "channelOrderNo": "2026060122001471831423371942",
                "complaintDeadline": "2026-06-05 13:31:38",
                "complaintDetail": "请提供客服电话，并要求退款",
                "complaintId": "21012924884",
                "complaintTag": "升级投诉",
                "complaintTime": "2026-06-01 10:18:32",
                "currency": "cny",
                "ifCode": "zftpay",
                "mchNo": "M1778058637",
                "payOrderId": "P2061262450926755842",
                "refundAmount": 0,
                "refundState": 0,
                "state": 2,
                "wayCode": "ALI_WAP"
            },
            {
                "amount": 9900,
                "appId": "69fb058daf98c3ede32f88c9",
                "channelOrderNo": "2026060122001471831423371942",
                "complaintDeadline": "2026-06-04 10:16:58",
                "complaintDetail": "看到群里发的一个投资项目，微信公众号搜索听弥，有高额回报，故下载了app。结果发现下载需要先充值去抽奖，然后返利套现，他们里面一直怂恿我充值，结果刚反应过来是骗局，赌博一类",
                "complaintId": "21012892995",
                "complaintTag": "",
                "complaintTime": "2026-06-01 10:14:07",
                "currency": "cny",
                "ifCode": "zftpay",
                "mchNo": "M1778058637",
                "payOrderId": "P2061262450926755842",
                "refundAmount": 0,
                "refundState": 1,
                "state": 2,
                "wayCode": "ALI_WAP"
            }
        ]
    },
    "sign": "1B3F24D0076FBA2E7BB626C62E12F49D"
    }

二、订单投诉详情

商户通过该接口查询订单投诉的详细信息，包括投诉内容、处理状态等。

1. 请求参数

字段名	参数名	必填	类型	示例值	描述
商户号	`mchNo`	是	String	M1778058637	商户号
应用ID	`appId`	是	String	69fb058daf98c3ede32f88c9	应用ID
请求时间	`reqTime`	是	String	1750137600	当前时间戳(秒)
版本号	`version`	是	String	1.0	接口版本号
签名类型	`signType`	是	String	MD5	签名类型(MD5/RSA)
签名	`sign`	是	String	C380BEC2BFD727A4B6845133519F3AD6	签名值
投诉单号	`complaintId`	是	String	200000020260610110466317127	投诉单号

2. 请求 URL

请求 URL：https://pay.xyzgpay.com/api/pay/complaint/detail

3. 请求示例数据

{
    "mchNo": "M1778058637",
    "appId": "69fb058daf98c3ede32f88c9",
    "reqTime": "1750137600",
    "version": "1.0",
    "signType": "MD5",
    "complaintId": "200000020260610110466317127",
    "sign": "C380BEC2BFD727A4B6845133519F3AD6"
    }

4. 返回参数(解密方式，将data值转成map，然后进行验签)

字段名	参数名	必填	类型	示例值	描述
返回码	`code`	是	int	0	返回码，0表示成功
返回信息	`msg`	是	String	SUCCESS	返回信息
签名	`sign`	否	String	879AF63054C7CA93E0FDE92AA4EFC76C	签名值
投诉单号	`complaintId`	是	String	21028776524	投诉单号
平台订单号	`payOrderId`	是	String	P2060328539623239681	支付中心生成的订单号
渠道订单号	`channelOrderNo`	是	String	2026052922001471831404171927	渠道侧订单号
商户号	`mchNo`	是	String	M1778058637	商户号
商户名称	`mchName`	是	String	月崖网络	商户名称
应用ID	`appId`	是	String	69fb058daf98c3ede32f88c9	应用ID
渠道代码	`ifCode`	是	String	zftpay	支付渠道代码
支付方式	`wayCode`	是	String	ALI_WAP	支付方式代码
订单金额	`amount`	是	long	9900	订单金额(单位：分)
投诉时间	`complaintTime`	是	String	2026-06-05 12:09:06	投诉时间
投诉详情	`complaintDetail`	是	String	在微信公众号无意间点击并且下载此类语音...	投诉详情描述
投诉标签	`complaintTag`	否	String		投诉标签(如：升级投诉)
投诉状态	`state`	是	int	2	投诉状态：0-待处理，1-处理中，3-处理完成，4-已撤销
用户投诉次数	`userComplaintTimes`	是	int	1	该用户投诉次数
是否等待用户回应	`incomingUserResponse`	是	boolean	false	是否等待用户回应
退款金额	`refundAmount`	是	long	0	已退款金额(单位：分)
退款状态	`refundState`	是	int	0	退款状态：0-未退款 1-已退款
处理备注	`remark`	否	String	经核查，用户投诉所提交...	处理备注信息
处理记录列表	`processingRecordList`	是	Array		投诉处理记录列表
processingRecordList 数组中的字段：
记录ID	`recordId`	是	long	1152	处理记录ID
投诉单号	`complaintId`	是	String	21028776524	投诉单号
记录类型	`recordType`	是	int	1	记录类型：1-用户提交投诉 2-平台处理中 3-订单信息 4-处理完成
处理内容	`content`	否	String	在微信公众号无意间点击并且下载此类语音...	处理内容描述
操作时间	`operateTime`	是	String	2026-06-05 12:09:06	操作时间

5. 返回示例数据

{
    "code": 0,
    "msg": "SUCCESS",
    "data": {
        "amount": 9900,
        "appId": "69fb058daf98c3ede32f88c9",
        "channelOrderNo": "2026052922001471831404171927",
        "complaintDetail": "在微信公众号无意间点击并且下载此类语音，贴子上说可以充值抽奖套现，爆率高，结果玩了几天，这听弥软件把我号封了，此时此刻发现自己被骗，联系也不给我退钱",
        "complaintId": "21028776524",
        "complaintTag": "",
        "complaintTime": "2026-06-05 12:09:06",
        "ifCode": "zftpay",
        "incomingUserResponse": false,
        "mchName": "月崖网络",
        "mchNo": "M1778058637",
        "payOrderId": "P2060328539623239681",
        "processingRecordList": [
            {
                "complaintId": "21028776524",
                "content": "在微信公众号无意间点击并且下载此类语音，贴子上说可以充值抽奖套现，爆率高，结果玩了几天，这听弥软件把我号封了，此时此刻发现自己被骗，联系也不给我退钱",
                "operateTime": "2026-06-05 12:09:06",
                "recordId": 1152,
                "recordType": 1
            },
            {
                "complaintId": "21028776524",
                "operateTime": "2026-06-05 12:12:56",
                "recordId": 1153,
                "recordType": 2
            },
            {
                "complaintId": "21028776524",
                "content": "交易金额:99.00; 商户单号:P2060328539623239681; 渠道单号:2026052922001471831404171927; 交易状态:WAIT_PROCESS; 状态描述:待处理; 投诉记录ID:376943378; 交易ID:419951940; 交易时间:2026-05-29 19:53:04; 退款时间:2026-06-05 12:12:57",
                "operateTime": "2026-06-05 12:12:57",
                "recordId": 1154,
                "recordType": 3
            },
            {
                "complaintId": "21028776524",
                "content": "处理结果码:不认可举报的证明材料; 处理备注:经核查，用户投诉所提交的证明材料内容不清晰、不完整，无法有效证明其投诉事由。平台已对相关聊天记录、语音内容及用户行为日志进行全面复核，未发现存在违规或不当行为。平台一贯严格遵守社区规范，致力于为用户提供健康、安全的语聊社交环境。若用户后续能提供更完整、有效的举证材料，我们将积极配合并重新核实处理。",
                "operateTime": "2026-06-05 15:19:17",
                "recordId": 1155,
                "recordType": 4
            }
        ],
        "refundAmount": 0,
        "refundState": 0,
        "remark": "经核查，用户投诉所提交的证明材料内容不清晰、不完整，无法有效证明其投诉事由。平台已对相关聊天记录、语音内容及用户行为日志进行全面复核，未发现存在违规或不当行为。平台一贯严格遵守社区规范，致力于为用户提供健康、安全的语聊社交环境。若用户后续能提供更完整、有效的举证材料，我们将积极配合并重新核实处理。",
        "state": 2,
        "userComplaintTimes": 1,
        "wayCode": "ALI_WAP"
    },
    "sign": "879AF63054C7CA93E0FDE92AA4EFC76C"
}

三、投诉处理

商户通过该接口处理投诉，支持多种处理动作：回复用户、反馈完成、处理投诉、退款进度更新等。

1. 请求参数

字段名	参数名	必填	类型	示例值	描述
商户号	`mchNo`	是	String	M1778058637	商户号
应用ID	`appId`	是	String	69fb058daf98c3ede32f88c9	应用ID
请求时间	`reqTime`	是	String	1750137600	当前时间戳(秒)
版本号	`version`	是	String	1.0	接口版本号
签名类型	`signType`	是	String	MD5	签名类型(MD5/RSA)
签名	`sign`	是	String	C380BEC2BFD727A4B6845133519F3AD6	签名值
投诉单号	`complaintId`	是	String(30)	21019634507	投诉单号
处理动作	`actionType`	是	String(32)	REPLY	处理动作：REPLY-回复用户，COMPLETE-反馈完成，PROCESS-处理投诉，REFUND_PROGRESS-退款进度更新
回复内容	`replyContent`	否	String(512)	您好，您的投诉已受理	回复内容（actionType为REPLY时必填）
备注	`remark`	否	String(512)	内部备注信息	处理备注
图片文件列表	`imgFileList`	否	String	["mediaId1", "mediaId2"]	图片文件列表JSON数组，存储已上传图片的mediaId
退款动作	`refundAction`	否	String(32)	APPROVE	退款动作：APPROVE-同意退款，REJECT-拒绝退款
发起退款日期	`launchRefundDay`	否	String(16)	2026-06-15	计划发起退款的日期
拒绝原因	`rejectReason`	否	String(256)	订单已完成，不支持退款	拒绝退款原因（refundAction为REJECT时必填）

2. 请求示例

    POST /api/pay/complaint/handle HTTP/1.1
    Host: pay.xxx.com
    Content-Type: application/x-www-form-urlencoded

    mchNo=M1778058637&appId=69fb058daf98c3ede32f88c9&reqTime=1750137600&version=1.0&signType=MD5&sign=C380BEC2BFD727A4B6845133519F3AD6&complaintId=21019634507&actionType=REPLY&replyContent=您好，您的投诉已受理，我们正在核实处理中，请耐心等待。

3. 响应参数

字段名	参数名	类型	描述
返回状态码	`code`	String	SUCCESS-成功，FAIL-失败
返回信息	`msg`	String	返回信息
签名	`sign`	String	签名值
数据对象	`data`	Object	响应数据对象

data 对象说明

字段名	参数名	类型	描述
投诉单号	`complaintId`	String	投诉单号
处理状态	`state`	String	SUCCESS-成功，FAIL-失败
处理结果描述	`message`	String	处理结果的描述信息
媒体文件ID	`mediaId`	String	上传图片返回的媒体文件ID（仅上传图片时返回）
文件名	`fileName`	String	上传图片返回的文件名（仅上传图片时返回）

4. 响应示例

    {
    "code": "SUCCESS",
    "msg": "SUCCESS",
    "data": {
        "complaintId": "21019634507",
        "state": "SUCCESS",
        "message": "处理成功",
        "mediaId": null,
        "fileName": null
    },
    "sign": "167C7BC644177F9537287C11E418AE6E"
    }

处理动作说明：

REPLY - 回复用户：向用户发送处理回复内容
COMPLETE - 反馈完成：标记投诉处理完成，通知平台已完成处理
PROCESS - 处理投诉：执行具体的投诉处理操作，通道处理编码由后端按动作自动生成
REFUND_PROGRESS - 退款进度更新：更新退款处理进度

四、投诉上传图片

商户通过该接口上传投诉处理凭证图片，返回图片的mediaId供后续投诉处理使用。

1. 请求参数

字段名	参数名	必填	类型	示例值	描述
商户号	`mchNo`	是	String	M1778058637	商户号
应用ID	`appId`	是	String	69fb058daf98c3ede32f88c9	应用ID
请求时间	`reqTime`	是	String	1750137600	当前时间戳(秒)
版本号	`version`	是	String	1.0	接口版本号
签名类型	`signType`	是	String	MD5	签名类型(MD5/RSA)
签名	`sign`	是	String	C380BEC2BFD727A4B6845133519F3AD6	签名值
投诉单号	`complaintId`	是	String(30)	21019634507	投诉单号
图片文件	`file`	是	MultipartFile	（二进制文件）	图片文件，支持JPG、PNG格式，文件大小不超过5MB

2. 请求示例

    POST /api/pay/complaint/uploadImage HTTP/1.1
    Host: pay.xxx.com
    Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

    ------WebKitFormBoundary7MA4YWxkTrZu0gW
    Content-Disposition: form-data; name="mchNo"

    M1778058637
    ------WebKitFormBoundary7MA4YWxkTrZu0gW
    Content-Disposition: form-data; name="appId"

    69fb058daf98c3ede32f88c9
    ------WebKitFormBoundary7MA4YWxkTrZu0gW
    Content-Disposition: form-data; name="reqTime"

    1750137600
    ------WebKitFormBoundary7MA4YWxkTrZu0gW
    Content-Disposition: form-data; name="version"

    1.0
    ------WebKitFormBoundary7MA4YWxkTrZu0gW
    Content-Disposition: form-data; name="signType"

    MD5
    ------WebKitFormBoundary7MA4YWxkTrZu0gW
    Content-Disposition: form-data; name="sign"

    C380BEC2BFD727A4B6845133519F3AD6
    ------WebKitFormBoundary7MA4YWxkTrZu0gW
    Content-Disposition: form-data; name="complaintId"

    21019634507
    ------WebKitFormBoundary7MA4YWxkTrZu0gW
    Content-Disposition: form-data; name="file"; filename="voucher.jpg"
    Content-Type: image/jpeg

    [图片二进制数据]
    ------WebKitFormBoundary7MA4YWxkTrZu0gW--

3. 响应参数

字段名	参数名	类型	描述
返回状态码	`code`	String	SUCCESS-成功，FAIL-失败
返回信息	`msg`	String	返回信息
签名	`sign`	String	签名值
数据对象	`data`	Object	响应数据对象

data 对象说明

字段名	参数名	类型	描述
投诉单号	`complaintId`	String	投诉单号
上传状态	`state`	String	SUCCESS-成功，FAIL-失败
上传结果描述	`message`	String	上传结果的描述信息
媒体文件ID	`mediaId`	String	上传成功后的媒体文件ID，可用于投诉处理接口

4. 响应示例

    {
    "code": "SUCCESS",
    "msg": "SUCCESS",
    "data": {
        "complaintId": "21019634507",
        "state": "SUCCESS",
        "message": "上传成功",
        "mediaId": "20260612001",
        "fileName": null
    },
    "sign": "167C7BC644177F9537287C11E418AE6E"
    }

使用说明：

图片格式支持JPG、PNG，建议使用JPG格式以节省存储空间
单个文件大小限制为5MB
上传成功后返回的mediaId可在投诉处理接口的imgFileList参数中使用
建议先上传图片获取mediaId，再调用投诉处理接口提交完整的处理信息

五、投诉回调接口

当商户侧有新的投诉或用户回复或投诉升级，支付系统会主动回调商户接口，将投诉信息推送给商户。

1. 回调参数说明

字段名	参数名	类型	描述
商户号	`mchNo`	String	商户号
应用ID	`appId`	String	应用ID
投诉单号	`complaintId`	String	投诉单号
渠道商编码	`ifCode`	String	渠道商编码
支付订单号	`payOrderId`	String	支付订单号
通道订单号	`channelOrderNo`	String	通道订单号
订单金额	`amount`	String	订单金额（单位：分）
投诉状态	`state`	String	投诉状态：0-待处理，1-处理中，3-处理完成，4-已撤销
投诉时间	`complaintTime`	String	投诉时间，格式：yyyy-MM-dd HH:mm:ss
投诉详情	`complaintDetail`	String	投诉详情描述
投诉标签	`complaintTag`	String	投诉标签，多个标签用逗号分隔
用户投诉次数	`userComplaintTimes`	String	用户投诉次数
请求时间	`reqTime`	String	请求时间戳（毫秒）
签名	`sign`	String	签名值，用于验证回调数据的合法性

2. 回调示例

{
    "ifCode" : "sftpay",
    "payOrderId" : "20260525210813qesg2791314_1290",
    "amount" : "39813",
    "userComplaintTimes" : "1",
    "sign" : "DA5FFD4CB464A57D210769F1A16F8B33",
    "channelOrderNo" : "4600000167202605259431176145",
    "complaintTime" : "2026-05-27 20:16:27",
    "reqTime" : "1781352561722",
    "complaintTag" : "",
    "complaintId" : "200000020260527200459645399",
    "complaintDetail" : "25号下的单，什么时间发货",
    "appId" : "6a1eadceaf980cf630c00954",
    "state" : "2",
    "mchNo" : "M1780395469"
}

3. 响应说明

商户接收到回调数据后，需要验证签名并返回响应：

响应状态	响应内容	说明
成功	`{"code":"SUCCESS","msg":"成功"}`	商户处理成功，支付系统将不再重试推送
失败	`{"code":"FAIL","msg":"失败原因"}`	商户处理失败，支付系统将按照重试策略重新推送

4. 签名验证

商户需要验证回调数据的签名，签名算法与接口签名一致：

签名规则：

将所有参与签名的参数按字典序排列（sign除外）
拼接成 key1=value1&key2=value2 的格式
在字符串末尾拼接商户密钥
使用MD5或RSA算法生成签名

使用说明：

商户需在后台配置投诉回调地址
回调地址必须支持POST请求，Content-Type为application/json
商户接收到回调后必须验证签名，确保数据来源合法
商户处理成功后需返回code为SUCCESS的JSON响应
如果商户处理失败，支付系统会在一定时间间隔后重试推送