Cashy 文档中心

创建代收订单

API EndPoint

POST baseUrl + /api/payIn

请求参数

参数名	必选	类型	字段说明	示例
`currency`	`Y`	`string(32)`	货币代码	`PHP`
`payType`	`Y`	`int`	代收支付产品编号	代收PayType枚举
`amount`	`Y`	`decimal(20,2)`	金额	`100-50000`
`reusableStatus`	`Y`	`boolean`	是否多次支付	目前只能是false
`mchOrderNo`	`Y`	`string(32)`	商户订单号
`expireTime`	`Y`	`long`	过期时间	默认3600秒 `不一定有效,部分通道支持`
`notifyUrl`	`Y`	`string(250)`	回调地址	`https://merchant.com/webhooks`
`nonceStr`	`Y`	`string(32)`	随机字符串
`remark`	`Y`	`string(32)`	备注	请使用英文字符
`realName`	`Y`	`string(32)`	代收付款人姓名	firstName-middleName-lastName
`payerAddress`	`Y`	`string(256)`	代收付款人地址	province-city-line1
`phone`	`Y`	`string(32)`	代收付款人手机号	09123456789
`idType`	`Y`	`string(32)`	付款人证件类型	代收付款人证件类型
`idCard`	`Y`	`string(32)`	代收付款人证件号
`email`	`Y`	`string(64)`	邮箱	`example@maildomain.com`

INFO

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

INFO

payerAddress为代收收款人地址，以province-city-line1格式拼接。此字段仅做只做格式校验，不做真实性校验。当使用还款码收款时（payType=410）必传。

省，市，收款人地址请使用-进行链接。省-市必须要是菲律宾的合法地区名。line1为代收付款人的简略地址,line1中如果有-符号需要替换为空格。

例如收款人位于Abra省，Tayum 市的 No. 12 Central Street ，那么payerAddress为 Abra-Tayum-No.12 Central Street

例如收款人位于Abra省，Tayum 市的 No. 12 Central-Street ，那么payerAddress为 Abra-Tayum-No.12 Central Street

TIP

请注意，当选择使用电子钱包支付方式时，我们会返回渠道的支付落地页，渠道有可能会根据用户的设备环境来选择展示二维码或者直接拉起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":"IDR","remark":"Electronic Cigarettes","nonceStr":"16a5a70f43384134bfae33acc77132e0"}'

响应参数

参数名	类型	说明
`merchantId`	`long`	商户Id
`mchOrderNo`	`string(32)`	商户订单号
`orderNo`	`string(32)`	平台订单号
`amount`	`decimal(20,2)`	金额
`orderFee`	`decimal(20,2)`	手续费
`payCode`	`string(32)`	付款账户VA
`biller`	`string(32)`	收款机构，在使用refNo/bankVa收款时使用
`payUrl`	`string(250)`	支付信息展示页/支付跳转URL

响应示例

成功响应异常响应

json

{
  "msg": "SUCCESS",
  "code": 200,
  "data": {
    "merchantId": "1002001",
    "mchOrderNo": "1386556787811426305",
    "orderNo": "PAYIN8551844049125523456",
    "payCode": "RN123456",
    "payUrl": "https://gcash.com/pay?bizNo=20241202111212800110166154827",
    "biller": "Gcash",
    "amount": "20000",
    "orderFee": "1700"
  }
}

json

{
  "msg": "Payin_Order_Error",
  "code": 500
}

TIP

请根据实际选择的代收PayType枚举使用payCode， biller ， payUrl等字段。如果您不想自己渲染展示信息，Cashy提供了一个展示页面，商户可以使用payUrl字段直接跳转到该页面，为用户展示支付信息。具体支持列表见下表。

payType值	支付产品名	`payCode`	`payUrl`	`biller`
401	QRPH_STATIC	二维码原始文本	Cashy提供的展示页面	N/A
402	QRPH_DYNAMIC	二维码原始文本	Cashy提供的展示页面	N/A
403	BANK_TRANSFER_INSTA	银行VA账号	Cashy提供的展示页面	收款机构
404	BANK_TRANSFER_PESONET	银行VA账号	Cashy提供的展示页面	收款机构
410	RefNo (Bill Payment)	还款码	Cashy提供的展示页面	收款机构，线下使用时需要告知收银人员
431	GCASH_WEB_ONLINE	N/A	支付URL	N/A
432	PAYMAYA_WEB_ONLINE	N/A	支付URL	N/A
433	COINS_WEB_ONLINE	N/A	支付URL	N/A
434	GRABPAY_WEB_ONLINE	N/A	支付URL	N/A
435	BPIA_WEB_ONLINE	N/A	支付URL	N/A
436	UBPB_WEB_ONLINE	N/A	支付URL	N/A

查询代收订单

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
  }
}

关于orderType为PATCH时的补充说明

用户不按照订单金额付款或者重复付款会出现补单订单，此时补单订单的orderType为PATCH:

orderNo是针对这笔订单新生成的平台订单号。
patchOrderNo 为关联的原订单的平台订单号，
patchMchOrderNo为关联的原订单的商户订单号。
mchOrderNo 为关联的原订单的商户订单号(带序列号标识)。注意，此时回调返回的 mchOrderNo 末尾会增加序列号标识，用于区分多笔部分还款的订单。

例如您的商户订单号是MCH20230088，当产生第一笔部分支付时，我们会在原订单的商户订单号mchOrderNo末尾增加序列号00001 ，您收到的回调的mchOrderNo就是MCH2023008800001，以此类推。

当发生补单行为时，我们的机器人也会在对应的商户群进行通知，通知会包含所有您需要的信息。

订单的orderType为API时:

patchOrderNo 和orderNo相同
patchMchOrderNo 和mchOrderNo相同

此时上述参数没有额外的意义。

TIP

fee 和 completionTime 仅在订单成功支付时有值。completionTime的格式为 yyyy-MM-dd HH:mm:ss。

代收订单结果通知

异步通知请求

通知地址由商户提供

POST Merchant NotifyUrl

异步通知请求参数

参数名	类型	说明
`merchantId`	`int`	商户Id
`mchOrderNo`	`string(32)`	商户订单号
`orderNo`	`string(32)`	平台订单号
`amount`	`decimal(20,2)`	金额
`fee`	`decimal(20,4)`	手续费
`payUrl`	`string(32)`	收银台Url
`payDeskUrl`	`string(250)`	收银台地址
`payType`	`string(32)`	代收PayType枚举
`orderStatus`	`string(32)`	代收订单状态枚举
`completionTime`	`date`	完成时间
`nonceStr`	`string(32)`	随机字符串
`patchOrderNo`	`string(32)`	关联的原订单的平台订单号
`patchMchOrderNo`	`string(32)`	关联的原订单的商户订单号
`orderType`	`string(32)`	API=API接口 MCH=商户后台 DESK=收银台 PATCH=补单

异步通知请求示例

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":"3002120","nonceStr":"1733116026894","orderNo":"PAYIN8551790545658687488","orderStatus":"SUCCESS","payCode":"OR.GPNQR..INOPROID_BS","payType":"41","payUrl":"https://payurl.com"}'

回调结构-API回调结构-补单

json

{
  "amount": 1000.0,
  "completionTime": "2024-11-24 21:56:55",
  "fee": 2.0,
  "mchOrderNo": "order_xxxxxxxxxxxxxx",
  "merchantId": "1012345",
  "nonceStr": "1732507016285",
  "orderNo": "PAYIN1234500000000001",
  "orderStatus": "SUCCESS",
  "orderType": "API",
  "patchMchOrderNo": "order_xxxxxxxxxxxxxx",
  "patchOrderNo": "PAYIN1234500000000001",
  "payCode": "60088888888888",
  "payType": "69",
  "payUrl": "https://xxxxx.xxxx.com/xxx/xx/xxx"
}

json

{
  "amount": 1000.0,
  "completionTime": "2024-11-24 21:56:55",
  "fee": 2.0,
  "mchOrderNo": "order_xxxxxxxxxxxxxx",
  "merchantId": "2004015",
  "nonceStr": "1732507016285",
  "orderNo": "PAYIN1234500000000002",
  "orderStatus": "SUCCESS",
  "orderType": "PATCH",
  "patchMchOrderNo": "order_xxxxxxxxxxxxxx0001",
  "patchOrderNo": "PAYIN1234500000000001",
  "payCode": "60088888888888",
  "payType": "69"
}

TIP

fee 和 completionTime 仅在订单成功支付时有值。completionTime的格式为 yyyy-MM-dd HH:mm:ss。

关于orderType为PATCH时的补充说明

用户不按照订单金额付款或者重复付款会出现补单订单，此时补单订单的orderType为PATCH:

orderNo是针对这笔订单新生成的平台订单号。
patchOrderNo 为关联的原订单的平台订单号，
patchMchOrderNo为关联的原订单的商户订单号。
mchOrderNo 为关联的原订单的商户订单号(带序列号标识)。注意，此时回调返回的 mchOrderNo 末尾会增加序列号标识，用于区分多笔部分还款的订单。

当发生补单行为时，我们的机器人也会在对应的商户群进行通知，通知会包含所有您需要的信息。

订单的orderType为API时:

patchOrderNo 和orderNo相同
patchMchOrderNo 和mchOrderNo相同

此时上述参数没有额外的意义。

TIP

Http响应状态码为200、301或302表示已正常发送回调,其它状态码我们会认为回调失败。回调失败后会在1,2,4,8,16,32,64,128,256,512分钟 重试，一共重试回调10次。

创建代收订单 ​

查询代收订单 ​

代收订单结果通知 ​

异步通知请求 ​

创建代收订单

查询代收订单

代收订单结果通知

异步通知请求