Cashy 文档中心

创建收银台订单

API EndPoint

POST baseUrl + /api/payDesk

请求参数

参数名	必选	类型	字段说明	示例说明
`currency`	`Y`	`string(32)`	货币代码	`PHP`
`amount`	`Y`	`decimal(20,0)`	金额	100-5000000
`reusableStatus`	`Y`	`boolean`	是否多次支付	目前只能是false
`mchOrderNo`	`Y`	`string(32)`	商户订单号
`expireTime`	`Y`	`long`	过期时间	默认3600秒 `部分支付产品支持`
`notifyUrl`	`Y`	`string(250)`	回调地址	`https://merchant.com/webhooks/payout`
`nonceStr`	`Y`	`string(32)`	随机字符串
`remark`	`Y`	`string(32)`	备注	请使用英文字符或不带重音的西语
`realName`	`Y`	`string(64)`	用户姓名	firstName-middleName-lastName
`idType`	`Y`	`string(32)`	付款人证件类型	代收付款人证件类型
`idCard`	`Y`	`string(32)`	付款人证件号
`returnUrl`	`N`	`string(250)`	同步跳转地址	（预留字段，暂不生效，支付成功后会跳到商户指定页面）
`phone`	`N`	`string(32)`	用户手机号	09123456789
`email`	`N`	`string(64)`	用户邮箱	`example@maildomain.com`

INFO

realName的firstName，middleName，lastName请使用-连接。若没有middleName可以使用空字符串代替。

INFO

注意，收银台代收只支持单次还款且固定金额的还款产品，如果需要使用RefNo（BillPayments），BankTransfer，请移步至 payin接口。

TIP

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

请求示例

bash

curl -L 'baseUrl/api/payDesk' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d '{"nonceStr":"1733129817080","currency":"PHP","amount":1064800,"reusableStatus":false,"mchOrderNo":"1313066365288624128","expireTime":28982,"notifyUrl":"https://merchant.com/payIn/callback","remark":"payin order","realName":"HAMZAN WADI  ","phone":"87761734941","idType":"1","idCard":"5203092009900005"}'

响应参数

参数名	类型	参数说明
`merchantId`	`int`	商户Id
`mchOrderNo`	`string(32)`	商户订单号
`orderNo`	`string(32)`	平台订单号
`amount`	`decimal(20,2)`	金额
`payUrl`	`string(250)`	收银台Url
`expireTime`	`date`	过期时间

响应示例

json

{
  "msg": "SUCCESS",
  "code": 200,
  "data": {
    "merchantId": "1002001",
    "mchOrderNo": "1313066365288624128",
    "orderNo": "PAYDESK38318551848652059590656",
    "payUrl": "https://paydesk.testpage.com/PAYDESK38318551848652059590656",
    "amount": "100000",
    "expireTime": "2022-12-06 17:48:40"
  }
}

查询收银台订单

API EndPoint

POST baseUrl + /api/payDeskQuery

请求参数

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

TIP

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

请求示例

bash

curl -L 'baseUrl/api/payDeskQuery' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d ' {"mchOrderNo":"202411301909131862936942783582208","nonceStr":"1138688daof9gnay3dt9j4wktxt1z99ww"}'

响应参数

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

响应示例

json

{
  "msg": "SUCCESS",
  "code": 200,
  "data": {
    "merchantId": "3002112",
    "mchOrderNo": "202411301909131862936942783582208",
    "orderNo": "PAYDESK39568551277959484616704",
    "payUrl": "https://idpaydesk2.brcashypro.com/index.html?PAYDESK39568551277959484616704",
    "amount": "1000000",
    "fee": "0",
    "orderStatus": "PAYING",
    "completionTime": null,
    "nonceStr": null
  }
}

收银台订单结果通知

通知地址由商户提供

POST Merchant NotifyUrl

异步通知请求参数

参数名	类型	说明
`mchOrderNo`	`string(32)`	商户订单号
`orderNo`	`string(32)`	平台订单号
`amount`	`decimal(20,2)`	金额
`fee`	`decimal(20,4)`	手续费
`payUrl`	`string(32)`	收银台Url
`orderStatus`	`string(32)`	收银台代收订单状态枚举
`completionTime`	`date`	完成时间
`nonceStr`	`string(32)`	随机字符串

异步通知请求示例

bash

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

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

json

{
  "amount": 358320.0,
  "completionTime": "2024-12-02 16:08:32",
  "fee": 9083.0,
  "mchOrderNo": "1313068703462109184",
  "merchantId": "1002001",
  "nonceStr": "1733130512894",
  "orderNo": "PAYDESK27618551850988355260416",
  "orderStatus": "SUCCESS",
  "payUrl": "https://idpaydesk2.brcashypro.com/index.html?PAYDESK27618551850988355260416"
}

json

{
  "amount": 358320.0,
  "completionTime": "2024-12-02 16:08:32",
  "fee": 9083.0,
  "mchOrderNo": "1313068703462109184",
  "merchantId": "1002001",
  "nonceStr": "1733130512894",
  "orderNo": "PAYDESK27618551850988355260416",
  "orderStatus": "FAIL",
  "payUrl": "https://idpaydesk2.brcashypro.com/index.html?PAYDESK27618551850988355260416"
}

TIP

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

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

创建收银台订单 ​

查询收银台订单 ​

查询收银台订单 ​

收银台订单结果通知 ​

创建收银台订单

查询收银台订单

查询收银台订单

收银台订单结果通知