Cashy 文档中心

创建代付订单

API EndPoint

POST baseUrl/api/payOut

请求参数

参数名	必选	类型	字段说明	示例值
`accountName`	`Y`	`string(64)`	收款人姓名`限制最长64个字符`	`Brandme`
`accountNo`	`Y`	`string(32)`	收款银行账号	`03126012345`
`accountType`	`Y`	`int`	账户类型	1 请参考代付账户类型
`currency`	`Y`	`string(32)`	货币代码	`PKR`
`amount`	`Y`	`decimal(20,2)`	金额	`[100.00,50000.00]`
`bankId`	`Y`	`int`	银行 Id	请参考代付银行列表
`mchOrderNo`	`Y`	`string(32)`	商户订单号	1386556787811426305
`notifyUrl`	`Y`	`String(250)`	回调地址	`https://merchant.com/webhooks`
`nonceStr`	`Y`	`string(32)`	随机字符串	1863484722378907648
`idCard`	`Y`	`string(32)`	收款人证件号	8220296123456
`phone`	`Y`	`string(32)`	收款人手机号`长度10位或者0开头11位`	3001234567
`email`	`Y`	`string(64)`	收款人邮箱	`example@maildomain.com`
`remark`	`Y`	`string(32)`	备注（请使用英文字符或不带重音的西语）	remark
`idType`	`N`	`string(32)`	代付收款人证件类型	暂无

请求示例

bash

curl -L 'baseUrl/api/payOut' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d '{"accountName":"Brandme","accountNo":"03126012345","accountType":"1","amount":"100","currency":"PKR","mchOrderNo":"test2280881511","nonceStr":"123456","notifyUrl":"https://testclient.idcashypay.com/stage-api/notify/test","remark":"test","bankId":"1","idCard":"8220296123456","email":"example@maildomain.com","phone":"3001234567"}'

响应参数

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

响应示例

成功响应异常响应

json

{
  "msg": "SUCCESS",
  "code": 200,
  "data": {
    "merchantId": "1002001",
    "mchOrderNo": "order000000001",
    "orderNo": "PAYOUT8232147000000000001",
    "amount": 100,
    "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次

创建代付订单 ​

查询代付订单 ​

代付订单结果通知 ​

创建代付订单

查询代付订单

代付订单结果通知