Cashy 文档中心

创建代付订单

API EndPoint

POST baseUrl + /api/payOut

请求参数

参数名	必选	类型	字段说明	示例值
`accountName`	`Y`	`string(40)`	收款人姓名
`accountNo`	`Y`	`string(32)`	收款账号	代付账户类型
`accountType`	`Y`	`int`	账户类型	代付账户类型
`currency`	`Y`	`string(32)`	货币代码	`MXN`
`amount`	`Y`	`decimal(20,0)`	金额	[40,15000]
`bankId`	`Y`	`int`	银行ID	38 代付银行列表查询
`mchOrderNo`	`Y`	`string(32)`	商户订单号	1386556787811426305
`notifyUrl`	`Y`	`String(250)`	回调地址	`https://merchant.com/webhooks`
`nonceStr`	`Y`	`string(32)`	随机字符串	1863484722378907648
`remark`	`Y`	`string(32)`	备注	请使用英文字符或不带重音的西语
`idType`	`N`	`string(32)`	代付收款人证件类型	暂不区分类型
`idCard`	`N`	`string(32)`	收款人证件号	用户真实证件号
`phone`	`N`	`string(32)`	收款人手机号
`email`	`N`	`string(64)`	收款人邮箱

TIP

银行支持列表以生产环境实际支持情况为准，建议您在进入生产环境前，调用我们的银行列表查询接口来确认生产银行支持情况。

请求示例

bash

curl -L 'baseUrl/api/payOut' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d '{"accountName":"Bob Jeck","accountNo":"1234567891011","accountType":"3","amount":"60000","bankId":"1","currency":"MXN","email":"bobs@gmail.com","mchOrderNo":"697670130731094","nonceStr":"7445560671","notifyUrl":"https://merchant.com/mxn/payout","phone":"6285767828472","remark":"payout order"}'

响应参数

参数名	类型	字段说明
`merchantId`	`int`	商户ID
`mchOrderNo`	`string(32)`	商户订单号
`orderNo`	`string(32)`	平台订单号
`amount`	`decimal(20,0)`	金额
`fee`	`decimal(20,0)`	手续费
`orderStatus`	`string`	订单状态请参考代付订单状态枚举

响应示例

成功响应异常响应

json

{
  "msg": "SUCCESS",
  "code": 200,
  "data": {
    "merchantId": "1002001",
    "mchOrderNo": "697670130731094",
    "orderNo": "PAYOUT8551827184491839488",
    "amount": "60000",
    "fee": "0",
    "orderStatus": "PROCESSING"
  }
}

json

{
  "msg": "System_error",
  "code": 500
}

Payout代付时序图

SPEI PAYOUT

商户请求/api/payOut接口提交付款订单。
Cashy对代付订单进行预处理。（校验一些必要参数）
返回处理结果商户。（如果成功接收则会返回平台订单号等信息，如果失败会返回对应的同步拒绝原因）

X. 当商户获得3的结果后，随时可以通过查询代付订单接口查询订单状态。

SPEI会验证订单，验证通过则会发送至收款行，失败则会返回失败原因。

W1. 第一次订单回调，如果交易被SPEI系统拒绝，则会通知订单失败，会携带订单失败原因，如果成功发送至收款行，则会回调订单成功。

收款行校验交易，如果校验通过则会存入收款客户账户，失败则会返回失败原因。（此过程大约两分钟）
用户收到款项后，主动操作退款。

W2. 如果收款行拒收/用户主动发起退款，则会存在第二次订单回调，同时会返回失败原因。

查询代付订单

API EndPoint

POST baseUrl + /api/payOutQuery

请求参数

参数名	必选	类型	示例值	字段说明
`mchOrderNo`	`N`	`string(32)`	1863484722378907648	商户订单号
`orderNo`	`N`	`string(32)`	PAYOUT8551739282639106048	平台订单号
`nonceStr`	`Y`	`string(32)`	9459931608	随机字符串

TIP

我们建议优先使用orderNo（平台订单号），平台订单号和商户订单号至少需要传递一个。

请求示例

bash

curl -L 'baseUrl/api/payOutQuery' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d '{"mchOrderNo":"1863484722378907648","nonceStr":"9459931608","orderNo":"PAYOUT8551739282639106048"}'

响应参数

参数名	类型	说明
`merchantId`	`int`	商户Id
`mchOrderNo`	`string(32)`	商户订单号
`orderNo`	`string(32)`	平台订单号
`channelOrderNo`	`string(32)`	渠道订单号
`amount`	`decimal(20,2)`	金额
`fee`	`decimal(20,2)`	手续费
`orderStatus`	`string(32)`	代付订单状态枚举
`resultDesc`	`string(64)`	订单状态具体描述
`completionTime`	`yyyy-MM-dd HH:mm:ss`	订单完成完成时间

响应示例

json

{
  "msg": "SUCCESS",
  "code": 200,
  "data": {
    "merchantId": "1002001",
    "mchOrderNo": "1863484722378907648",
    "orderNo": "PAYOUT8551739282639106048",
    "amount": "60000",
    "fee": "5150",
    "orderStatus": "PAYING",
    "completionTime": null,
    "resultDesc": null
  }
}

代付订单结果通知

通知地址由商户提供

POST Merchant NotifyUrl

异步通知请求参数

参数名	类型	说明
`merchantId`	`int`	商户Id
`mchOrderNo`	`string(32)`	商户订单号
`orderNo`	`string(32)`	平台订单号
`channelOrderNo`	`string(32)`	渠道订单号
`amount`	`decimal(20,2)`	金额
`fee`	`decimal(20,4)`	手续费
`orderStatus`	`string(32)`	代付订单状态枚举
`resultDesc`	`string(64)`	订单状态具体描述
`completionTime`	`yyyy-MM-dd HH:mm:ss`	订单完成完成时间

异步通知请求示例

bash

curl -L 'merchant.com/webhools/payout' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d '{"amount":60000.00,"completionTime":"2024-12-02 08:42:54","fee":5150.0000,"mchOrderNo":"1863484722378907648","merchantId":"3002124","nonceStr":"1733103774518","orderNo":"PAYOUT8551739282639106048","orderStatus":"SUCCESS","payType":"11"}'

回调结构-成功回调结构-失败

json

{
  "amount": 60000.0,
  "completionTime": "2024-12-02 08:42:54",
  "fee": 5150.0,
  "mchOrderNo": "1863484722378907648",
  "merchantId": "1002001",
  "nonceStr": "1733103774518",
  "orderNo": "PAYOUT8551739282639106048",
  "orderStatus": "SUCCESS",
  "payType": "11"
}

json

{
  "amount": 60000.0,
  "completionTime": "2024-12-02 08:42:54",
  "fee": 5150.0,
  "mchOrderNo": "1863484722378907648",
  "merchantId": "1002001",
  "nonceStr": "1733103774518",
  "orderNo": "PAYOUT8551739282639106048",
  "orderStatus": "FAIL",
  "resultDesc": "ACCOUNT NOT EXITS",
  "payType": "11"
}

订单结果反转处理

请注意，极少数的情况下代付订单会发生结果反转通知，您的回调处理逻辑应当考虑成功->失败，失败->成功状态的处理。

异步通知响应示例

json

{
  "status": "SUCCESS"
}

TIP

当回调响应HTTP状态码为200、301或302时，我们认为商户已经成功接收并处理回调, 其它状态我们会认为商户处理回调失败。

回调失败后会在1,2,4,8,16,32,64,128,256,512分钟重试，一共重试回调10次

创建代付订单 ​

Payout代付时序图 ​

查询代付订单 ​

代付订单结果通知 ​

创建代付订单

Payout代付时序图

查询代付订单

代付订单结果通知