Cashy 文档中心

创建代付订单

API EndPoint

POST baseUrl + /api/payOut

请求参数

参数名	必选	类型	字段说明	示例值
`accountName`	`Y`	`string(64)`	收款人名称`限制最长64个字符`	John
`accountNo`	`Y`	`string(32)`	收款人账户(移动钱包号)	721323213
`accountType`	`Y`	`int`	账户类型	请参考代付账户类型
`currency`	`Y`	`string(32)`	货币代码	`TZS`
`amount`	`Y`	`decimal(20,0)`	金额(整数),最小500,最大3000000	`10000`
`mchOrderNo`	`Y`	`string(32)`	商户订单号	1386556787811426305
`notifyUrl`	`Y`	`string(250)`	回调地址	`https://merchant.com/webhooks`
`nonceStr`	`Y`	`string(32)`	随机字符串	1863484722378907648
`idType`	`N`	`string(32)`	收款人证件类型	暂不区分类型
`idCard`	`N`	`string(32)`	收款人证件号	用户真实证件号
`phone`	`N`	`string(32)`	收款人手机号	+255xxxxxxx
`email`	`N`	`string(64)`	收款人邮箱	example@maildomain.com
`remark`	`Y`	`string(32)`	备注（请使用英文字符或不带重音的西语）	remark

请求示例

bash

curl -L 'baseUrl/api/payOut' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d '{"nonceStr":"xxxxxxxx","accountName":"jack","accountNo":"713512345","accountType":"1","currency":"TZS","amount":30000,"bankId":2,"mchOrderNo":"orderxxxxxxxxxxxxx","notifyUrl":"https://xxxxx.com/payOut/callback","idType":"1","idCard":"19870331141130000329","phone":"713512345","email":"jack@gmail.com","remark":"xxxxx"}'

响应参数

参数名	类型	参数说明
`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": "orderxxxxxxxxxxxxx",
    "orderNo": "PAYOUTxxxxxxxxxxxxxxxxxx",
    "amount": 30000,
    "fee": 0,
    "orderStatus": "PROCESSING"
  }
}

json

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

查询代付订单

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次

创建代付订单 ​

查询代付订单 ​

代付订单结果通知 ​

创建代付订单

查询代付订单

代付订单结果通知