Cashy 文档中心

创建代付订单

API EndPoint

POST baseUrl + /api/payOut

请求参数

参数名	必选	类型	字段说明	示例
`accountName`	`Y`	`string(64)`	收款人名称	`限制最长64个字符`
`accountNo`	`Y`	`string(32)`	收款银行账号
`cciAccountNo`	`N`	`string(32)`	收款银行CCI账号	20位，代付收款银行非四大行时必传
`accountType`	`Y`	`int`	账户类型	代付账户类型
`currency`	`Y`	`string(32)`	货币代码	`PEN`
`amount`	`Y`	`decimal(20,2)`	金额	`[10.00,10000.00]`
`bankId`	`Y`	`int`	银行ID	代付银行列表查询
`mchOrderNo`	`Y`	`string(32)`	商户订单号
`notifyUrl`	`Y`	`String(250)`	回调地址
`nonceStr`	`Y`	`string(32)`	随机字符串
`idType`	`Y`	`string(32)`	收款人证件类型	代付收款人证件类型
`idCard`	`Y`	`string(32)`	收款人证件号	需要是收款账户对应的开户证件号
`remark`	`Y`	`string(32)`	备注	请使用英文字符或不带重音的西语
`phone`	`N`	`string(32)`	收款人手机号	需要是收款用户真实手机号
`email`	`N`	`string(64)`	收款人邮箱	必须是合法邮箱地址，不同用户不能重复

请求示例

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":"IDR","email":"bobs@gmail.com","mchOrderNo":"697670130731094","nonceStr":"7445560671","notifyUrl":"https://merchant.com/idr/payout","phone":"6285767828472","remark":"payout order"}'

响应参数

参数名	类型	参数说明
`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": "697670130731094",
    "orderNo": "PAYOUT8551827184491839488",
    "amount": "60000",
    "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次

创建代付订单 ​

查询代付订单 ​

代付订单结果通知 ​

创建代付订单

查询代付订单

代付订单结果通知