代付接口 std1

三个接口：提代付、查代付、查余额；代付有结果时我们回调您（见回调）。都是 POST 表单，应答是一层 JSON。

公共规则

请求：POST，Content-Type: application/x-www-form-urlencoded; charset=UTF-8。参数只放正文，地址上的查询串一律忽略。
参数名只许英文字母、数字、下划线；同一个参数出现两次，按参数错误拒。
请求正文不超过 65536 字节。
应答：HTTP 200，application/json; charset=UTF-8，一层 JSON、值全是字符串（金额也是字符串）；没有值的字段不出现。
HTTP 不是 200、正文不是 JSON、验签不过：一律当「结果不明」，见错误码。
msg 是给人看的中文，程序只认 code。
没有时间戳和随机串：防重复靠「同一个商户单号只处理一次」。
三个接口都查代付 IP 白名单，名单为空时全部拒绝。

提代付

项目	值
方法	`POST`
地址	`https://api.xx2system.xyz/std1/payout/apply`
请求正文	`application/x-www-form-urlencoded; charset=UTF-8`
正文上限	65536 字节
限流	每秒 20 次
IP 白名单	按代付 IP 名单查；名单为空时全部拒绝
应答	`application/json; charset=UTF-8`

请求参数

参数	必填	规则	说明
`mchId`	是	格式 `[A-Za-z0-9_-]{1,32}`	商户号
`mchOrderNo`	是	格式 `[A-Za-z0-9_-]{1,64}`	您的商户单号，同一商户唯一；结果不明时用它重发（见「同一个商户单号再发一次」）
`amount`	是	格式 `[1-9][0-9]{0,11}`	代付金额，整数，按货币最小单位；两位小数的货币 10000 表示 100.00
`currency`	否	3 位大写字母，只收本平台币种（CNY）；不传就是它	币种
`accountName`	是	1–64 个字符；首尾不能有空白；不能有控制字符；不能有零宽、双向控制这类看不见的字符	收款户名
`accountNo`	是	格式 `[\x21-\x7E]{5,255}`	收款账号：银行卡号、钱包账号等，5–255 个可见英文字符（字母、数字、符号），原样收、不去空格、不改大小写
`bankName`	是	1–64 个字符；首尾不能有空白	开户银行名称（按名字认，不用银行编码）
`bankBranch`	否	最多 128 个字符	支行
`bankProvince`	否	最多 32 个字符	开户行所在省
`bankCity`	否	最多 32 个字符	开户行所在市
`notifyUrl`	否	最多 256 个字符；以 `http://` / `https://` 开头	结果回调地址；不传就不回调，您靠查单
`remark`	否	最多 128 个字符	您自己的备注；查单、回调原样带回，不发给上游
`productId`	否	格式 `[A-Za-z0-9_-]{1,32}`	正式产品ID编码请联系客服提供；不传就走您的默认代付产品。传了没开通或已关闭的产品，回 MERCHANT_DISABLED
`sign`	是	格式 `[0-9A-Fa-f]{64}`	签名，见「签名」

productId 选这一笔走您的哪个代付产品，手续费按这个产品收；通道由我们在这个产品里选。不传就走默认代付产品，已经对接的不用改。
还可以带您自己的参数（名字别和上面的重复），一起签名，我们验签后忽略。
没有银行编码：开户行只按名字认。

应答

参数	什么时候有	说明
`code`	总有（`SUCCESS`）	结果码，见「错误码」
`mchId`	总有	商户号
`mchOrderNo`	总有	商户单号
`payoutNo`	总有	本平台代付单号
`amount`	总有	代付金额（最小单位）
`fee`	总有	手续费（最小单位），受理时定下
`currency`	总有	币种
`createTime`	总有	受理时间，北京时间
`sign`	总有	签名
`msg`	失败应答里有	失败原因（中文，给人看）

code=SUCCESS 是已受理、钱已冻结，不是已出款。最终结果看回调或查单。
受理应答里没有状态字段。
开通了代付接口二次确认的：我方在受理这次代付请求时就会调用确认地址，回成功值才受理，否则回 ORDER_CONFIRM_FAILED。调代付接口前请先把订单存好，确认地址被问时要查得到。

同一个商户单号再发一次

这个单号	这次的参数	您收到
已受理	和第一次完全相同	和第一次逐字节相同的受理应答，不会再出一笔
已被拒	和第一次完全相同	和第一次相同的拒绝应答
已受理或已被拒	有任何不同	`ORDER_NO_CONFLICT`：这次没执行，原单不受影响
没有记录	—	当新请求处理

「完全相同」＝除 sign 外的全部非空参数，值一样（空串等于没传）。currency 第一次带了、第二次没带，算不同。
结果不明时只用原单号、原参数重发。换单号重下是唯一会出两次钱的做法。
同一张卡、同样的金额用新单号再提，就是一笔新代付，我们照样执行。

示例

示例密钥（假的）：0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef；示例商户号：DEMO0001

POST https://api.xx2system.xyz/std1/payout/apply

签名串

accountName=张三&accountNo=6222021234567890123&amount=10000&bankName=中国工商银行&mchId=DEMO0001&mchOrderNo=ORDER-20260917-0001

sign

4d368047ec349d118d7865c7bcba91f1f152c72b41bba9f389be963630a22064

请求正文

accountName=%E5%BC%A0%E4%B8%89&accountNo=6222021234567890123&amount=10000&bankName=%E4%B8%AD%E5%9B%BD%E5%B7%A5%E5%95%86%E9%93%B6%E8%A1%8C&mchId=DEMO0001&mchOrderNo=ORDER-20260917-0001&sign=4d368047ec349d118d7865c7bcba91f1f152c72b41bba9f389be963630a22064

应答（受理：钱已冻结，不是已出款）

{"code":"SUCCESS","mchId":"DEMO0001","mchOrderNo":"ORDER-20260917-0001","payoutNo":"P20260917120000000001","amount":"10000","fee":"200","currency":"CNY","createTime":"2026-09-17 12:00:00","sign":"13dc9a6b36d02a8dc8fe08117a4b85cdf9e69d3bc50cc7c5010df98263d809e0"}

应答（被拒（B 类）：订单已拒绝（终态），商户订单号已占用）

{"code":"INSUFFICIENT_BALANCE","msg":"可用余额不足","mchId":"DEMO0001","mchOrderNo":"ORDER-20260917-0001","sign":"9213d0f28d29dd694bf15c5797c985a3926a059157dfefaa81f71aae57c52331"}

查代付

项目	值
方法	`POST`
地址	`https://api.xx2system.xyz/std1/payout/query`
请求正文	`application/x-www-form-urlencoded; charset=UTF-8`
正文上限	65536 字节
限流	每秒 50 次
IP 白名单	按代付 IP 名单查；名单为空时全部拒绝
应答	`application/json; charset=UTF-8`

请求参数

参数	必填	规则	说明
`mchId`	是	格式 `[A-Za-z0-9_-]{1,32}`	商户号
`mchOrderNo`	二选一	格式 `[A-Za-z0-9_-]{1,64}`	您的商户单号，同一商户唯一；结果不明时用它重发（见「同一个商户单号再发一次」）
`payoutNo`	二选一	格式 `[A-Za-z0-9]{1,32}`	本平台代付单号（受理应答里给的）
`sign`	是	格式 `[0-9A-Fa-f]{64}`	签名，见「签名」

mchOrderNo、payoutNo 至少给一个；两个都给时必须是同一笔，否则回 ORDER_NOT_FOUND。

应答

参数	什么时候有	说明
`code`	总有（`SUCCESS`）	结果码，见「错误码」
`mchId`	总有	商户号
`mchOrderNo`	总有	商户单号
`payoutNo`	总有	本平台代付单号
`amount`	总有	代付金额（最小单位）
`fee`	总有	手续费（最小单位），受理时定下
`currency`	总有	币种
`status`	总有	代付状态，见下面「状态」
`createTime`	总有	受理时间，北京时间
`finishTime`	status 是 `FAILED` / `REVERSED` / `SUCCESS` 时有	进入当前状态的时间
`failMsg`	status 是 `FAILED` 时有	撤单原因
`remark`	总有	申请时的备注
`sign`	总有	签名
`msg`	失败应答里有	失败原因（中文，给人看）

查的是一笔被拒的单：回当初那个拒绝码。
查不到回 ORDER_NOT_FOUND：不能据此认定没建单，申请可能还在路上。
不返回收款人信息，也不返回任何通道信息。

状态

状态	意思
`PROCESSING`	处理中：已受理，钱冻着，还没有最终结果。可能持续几小时到几天，不会重复出款
`SUCCESS`	已出款
`FAILED`	已撤单，钱已退回可用余额
`REVERSED`	出款后被退回（冲正），钱已退回

您能看到的变化只有两条路：PROCESSING → SUCCESS → REVERSED、PROCESSING → FAILED。REVERSED（冲正）不发回调，只能查单看到。
PROCESSING 可能持续几小时到几天（上游结果要人工核实时）。期间钱冻着、不会重复出款；不要换单号重下，可以凭 payoutNo 找运营。

示例

示例密钥（假的）：0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef；示例商户号：DEMO0001

POST https://api.xx2system.xyz/std1/payout/query

签名串

mchId=DEMO0001&mchOrderNo=ORDER-20260917-0001

sign

20f17f6d87cf293d6ced8c01c4c40d887d7846161e306d7610828fe333c83b25

请求正文

mchId=DEMO0001&mchOrderNo=ORDER-20260917-0001&sign=20f17f6d87cf293d6ced8c01c4c40d887d7846161e306d7610828fe333c83b25

应答（已出款）

{"code":"SUCCESS","mchId":"DEMO0001","mchOrderNo":"ORDER-20260917-0001","payoutNo":"P20260917120000000001","amount":"10000","fee":"200","currency":"CNY","status":"SUCCESS","createTime":"2026-09-17 12:00:00","finishTime":"2026-09-17 12:05:30","sign":"6d415f531376788d1e915e70deeffb44e96f669aba651f32e33933255f650fa2"}

查余额

项目	值
方法	`POST`
地址	`https://api.xx2system.xyz/std1/balance/query`
请求正文	`application/x-www-form-urlencoded; charset=UTF-8`
正文上限	65536 字节
限流	每秒 10 次
IP 白名单	按代付 IP 名单查；名单为空时全部拒绝
应答	`application/json; charset=UTF-8`

请求参数

参数	必填	规则	说明
`mchId`	是	格式 `[A-Za-z0-9_-]{1,32}`	商户号
`currency`	否	3 位大写字母，只收本平台币种（CNY）；不传就是它	币种
`sign`	是	格式 `[0-9A-Fa-f]{64}`	签名，见「签名」

应答

参数	什么时候有	说明
`code`	总有（`SUCCESS`）	结果码，见「错误码」
`mchId`	总有	商户号
`currency`	总有	币种
`balance`	总有	总余额（最小单位），含冻结中的
`frozenAmount`	总有	冻结中（最小单位）：在途代付、结算申请冻着的钱
`availableAmount`	总有	可用余额（最小单位）＝总余额－冻结中
`sign`	总有	签名
`msg`	失败应答里有	失败原因（中文，给人看）

availableAmount＝balance－frozenAmount。开了「允许负余额」的商户，余额可能是负数。

示例

示例密钥（假的）：0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef；示例商户号：DEMO0001

POST https://api.xx2system.xyz/std1/balance/query

签名串

mchId=DEMO0001

sign

a896e78745bd80092e80a28976a4f758ca0a713d74228db79806337828fd9695

请求正文

mchId=DEMO0001&sign=a896e78745bd80092e80a28976a4f758ca0a713d74228db79806337828fd9695

应答（查余额）

{"code":"SUCCESS","mchId":"DEMO0001","currency":"CNY","balance":"500000","frozenAmount":"10200","availableAmount":"489800","sign":"0b6b91b47831daa89b4c350a6eb38b755d998df8fc168e503b68bacfa5b634fd"}

代付接口 std1

公共规则 #

提代付 #

请求参数 #

应答 #

同一个商户单号再发一次 #

示例 #

查代付 #

请求参数 #

应答 #

状态 #

示例 #

查余额 #

请求参数 #

应答 #

示例 #

公共规则

提代付

请求参数

应答

同一个商户单号再发一次

示例

查代付

请求参数

应答

状态

示例

查余额

请求参数

应答

示例