Cashy 文档中心

创建代收订单

API EndPoint

POST baseUrl + /api/payIn

请求参数

参数名	必选	类型	字段说明	示例值
`currency`	`Y`	`string(32)`	货币代码(`CLP`)	`CLP`
`payType`	`Y`	`int`	支付产品类型	代收PayType枚举 200
`amount`	`Y`	`decimal(20,0)`	金额	`1000-5000000`
`reusableStatus`	`Y`	`boolean`	目前只能是false	false
`mchOrderNo`	`Y`	`string(32)`	商户订单号（不允许重复）	mch12345
`expireTime`	`Y`	`long`	过期时间（单位：秒）默认3600秒 `不一定有效,部分通道支持`	3600
`notifyUrl`	`Y`	`string(250)`	回调地址	`https://merchant.com/webhooks`
`nonceStr`	`Y`	`string(32)`	随机字符串	1863484722378907648
`realName`	`Y`	`string(64)`	付款人姓名，不做真实性校验`限制最长64个字符`	Jack
`phone`	`Y`	`string(32)`	付款人手机号，用户真实手机号	9712345678
`email`	`Y`	`string(64)`	付款人邮箱，请尽量提供真实邮箱地址	`example@maildomain.com`
`idType`	`Y`	`string(32)`	请参考代收付款人证件类型	1
`idCard`	`Y`	`string(32)`	付款人证件号,会对RUT进行格式校验	`11.111.111-1`
`remark`	`Y`	`string(32)`	备注（请使用英文字符或不带重音的西语）	remark

INFO

代收发起 idType,增加代收付款人证件类型。（2023/09/22）

TIP

请注意，当选择使用MACH等电子钱包支付方式时，我们会返回渠道的支付落地页，渠道有可能会根据用户的设备环境来选择展示二维码或者直接拉起APP支付，如果您采用了APP内嵌webview技术方案渲染页面，请注意兼容处理URL SCHEME拉起App支付的逻辑。

请求示例

bash

curl -L 'baseUrl/api/payIn' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d '{"realName":"Reza Wijaya","amount":"20000.00","reusableStatus":false,"payType":"43","expireTime":3600,"mchOrderNo":"1386556787811426305","notifyUrl":"https://merchant.com/webhooks/payin","currency":"CLP","remark":"Electronic Cigarettes","nonceStr":"16a5a70f43384134bfae33acc77132e0"}'

响应参数

参数名	类型	说明
`merchantId`	`long`	商户Id
`mchOrderNo`	`string(32)`	商户订单号
`orderNo`	`string(32)`	平台订单号
`amount`	`decimal(20,0)`	金额
`orderFee`	`decimal(20,0)`	手续费
`payCode`	`string(32)`	付款账户VA
`payUrl`	`string(250)`	收银台支付地址

响应示例

成功响应

json

{
  "msg": "SUCCESS",
  "code": 200,
  "data": {
    "merchantId": "1002001",
    "mchOrderNo": "1386556787811426305",
    "orderNo": "PAYIN8551844049125523456",
    "payCode": "",
    "payUrl": "https://m.dana.id/link/pay?bizNo=20241202111212800110166154827",
    "payDeskUrl": "https://m.dana.id/link/pay?bizNo=20241202111212800110166154827",
    "amount": "20000",
    "orderFee": "1700"
  }
}

测试用例

对于代收交易，请使用以下卡进行测试。

卡类型	卡信息	结果
`VISA`	4051 8856 0044 6623 CVV 123	成功
`AMEX`	3700 0000 0002 032 CVV 1234	成功
`MASTERCARD`	5186 0595 5959 0568 CVV 123	失败
`Redcompra`	4051 8842 3993 7763	成功
`Redcompra`	5186 0085 4123 3829	失败
`Prepago VISA`	4051 8860 0005 6590 CVV 123	成功
`Prepago MASTERCARD`	5186 1741 1062 9480 CVV 123	失败

当出现带有RUT和密钥的身份验证时，必须使用RUT 11.111.111-1 ,密钥123 。

查询代收订单

API EndPoint

POST baseUrl + /api/payInQuery

请求参数

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

TIP

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

请求示例

bash

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

响应参数

参数名	类型	字段说明
`merchantId`	`int`	商户Id
`mchOrderNo`	`string(32)`	商户订单号
`orderNo`	`string(32)`	平台订单号
`channelOrderNo`	`string(32)`	渠道订单号
`payType`	`string(32)`	代收PayType枚举
`payCode`	`string(32)`	支付码
`payUrl`	`string(250)`	付款二维码
`amount`	`decimal(20,0)`	金额
`fee`	`decimal(20,4)`	手续费
`orderStatus`	`string(32)`	代收订单状态枚举
`completionTime`	`date`	完成时间

响应示例

支付中成功

json

{
  "msg": "SUCCESS",
  "code": 200,
  "data": {
    "merchantId": "1002001",
    "mchOrderNo": "1386556575370063873",
    "orderNo": "PAYIN8551843837024997376",
    "payType": "43",
    "payCode": "",
    "payUrl": "https://m.dana.id/link/pay?bizNo=202412021112128001101660361270",
    "payDeskUrl": "https://idpaydesk2.brcashypro.com/views/pay.html?PAYIN8551843837024997376",
    "amount": "20000",
    "fee": "1700",
    "orderStatus": "PAYING",
    "completionTime": null,
    "nonceStr": null
  }
}

json

{
  "msg": "SUCCESS",
  "code": 200,
  "data": {
    "merchantId": "1002001",
    "mchOrderNo": "1386556575370063873",
    "orderNo": "PAYIN8551843837024997376",
    "payType": "43",
    "payCode": "",
    "payUrl": "https://m.dana.id/link/pay?bizNo=202412021112128001101660361270",
    "payDeskUrl": "https://idpaydesk2.brcashypro.com/views/pay.html?PAYIN8551843837024997376",
    "amount": "20000",
    "fee": "1700",
    "orderStatus": "SUCCESS",
    "completionTime": "2024-12-02 15:40:50",
    "nonceStr": null
  }
}

代收订单结果通知

通知地址由商户提供

POST Merchant NotifyUrl

异步通知请求参数

参数名	类型	说明
`merchantId`	`int`	商户Id
`mchOrderNo`	`string(32)`	商户订单号
`orderNo`	`string(32)`	平台订单号
`channelOrderNo`	`string(32)`	渠道订单号
`payType`	`string(32)`	代收PayType枚举
`payCode`	`string(32)`	支付码
`payUrl`	`string(250)`	付款二维码
`amount`	`decimal(20,0)`	金额
`fee`	`decimal(20,4)`	手续费
`orderStatus`	`string(32)`	代收订单状态枚举
`completionTime`	`date`	完成时间

异步通知请求示例

bash

curl -L 'merchant.com/webhooks/payin' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d '{"amount":20000.00,"completionTime":"2024-12-02 12:07:06","fee":2500.0000,"mchOrderNo":"1386503284355244033","merchantId":"1002001","nonceStr":"1733116026894","orderNo":"PAYIN8551790545658687488","orderStatus":"SUCCESS","payCode":"OR.GPNQR..INOPROID_BS","payType":"41","payUrl":"https://payurl.com"}'

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

json

{
  "amount": 20000.0,
  "completionTime": "2024-12-02 12:07:06",
  "fee": 2500.0,
  "mchOrderNo": "1386503284355244033",
  "merchantId": "1002001",
  "nonceStr": "1733116026894",
  "orderNo": "PAYIN8551790545658687488",
  "orderStatus": "SUCCESS",
  "payCode": "OR.GPNQR..INOPROID_BS",
  "payType": "41",
  "payUrl": "https://payurl.com"
}

json

{
  "amount": 20000.0,
  "completionTime": "2024-12-02 12:07:06",
  "fee": 2500.0,
  "mchOrderNo": "1386503284355244033",
  "merchantId": "1002001",
  "nonceStr": "1733116026894",
  "orderNo": "PAYIN8551790545658687488",
  "orderStatus": "FAIL",
  "payCode": "OR.GPNQR..INOPROID_BS",
  "payType": "41",
  "payUrl": "https://payurl.com"
}

TIP

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

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

创建代收订单 ​

测试用例 ​

查询代收订单 ​

代收订单结果通知 ​

创建代收订单

测试用例

查询代收订单

代收订单结果通知