Cashy 文档中心

创建代付订单

API EndPoint

POST baseUrl + /api/payOut

请求参数

参数名	必选	类型	说明	示例值
`accountName`	`Y`	`string(64)`	收款人名称`限制最长64个字符`	Brandme
`accountNo`	`Y`	`string(32)`	收款人账户	`646180000000000007`
`accountType`	`Y`	`int`	账户类型	请参考代付账户类型
`currency`	`Y`	`string(32)`	货币代码	COP
`amount`	`Y`	`decimal(20,2)`	金额最少10000-最大5000000	10000
`bankId`	`Y`	`int`	银行Id ）	请参考代付银行列表查询
`mchOrderNo`	`Y`	`string(32)`	商户订单号	1386556787811426305
`notifyUrl`	`Y`	`String(250)`	回调地址	`https://merchant.com/webhooks`
`nonceStr`	`Y`	`string(32)`	随机字符串	1863484722378907648
`idType`	`Y`	`string(32)`	代付收款人证件类型	请参考代付收款人证件类型
`idCard`	`Y`	`string(32)`	收款人证件号，纯数字。`银行会校验证件和收款帐户的开户证件是否一致,否则会代付失败`	收款人证件号
`phone`	`N`	`string(32)`	收款人手机号	+57xxxxxxx
`email`	`N`	`string(64)`	收款人邮箱	`example@maildomain.com`
`remark`	`N`	`string(32)`	备注（请使用英文字符或不带重音的西语）	不传默认 `remark`

TIP

关于idType字段，请以收款银行账户开设时使用的实际证件类型为准，不一致会导致代付失败。

举例：如果用户开户使用的是NIT证件，发起代付是透传的证件类型为CC, 此时会导致代付失败。

请求示例

bash

curl -L 'baseUrl/api/payOut' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d '{"amount":50000.00,"bankId":33,"idType":"1","accountName":"Jeson","mchOrderNo":"order00000001","idCard":"43912345","accountNo":"3023612345","accountType":"0","notifyUrl":"https://xxxxxx.com/notify","currency":"COP","remark":"remark","nonceStr":"123456789"}'

响应参数

参数名	类型	说明
`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": "PAYOUT00000000000001",
    "amount": 50000.0,
    "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次

创建代付订单 ​

查询代付订单 ​

代付订单结果通知 ​

创建代付订单

查询代付订单

代付订单结果通知