Cashy 文档中心

创建代收订单

HTTP请求信息

TIP

POST baseUrl + /api/payIn

HTTP请求头

请求头	必选	值
`Content-Type`	`Y`	`application/json`
`MerchantId`	`Y`	`MerchantId`
`Sign`	`Y`	`Sign`

HTTP请求体

参数名	必选	类型	示例值	字段说明
`currency`	`Y`	`string(32)`	`MXN`	货币代码
`payType`	`Y`	`int`	69	请查看代收PayType枚举
`amount`	`Y`	`decimal(20,0)`	[40,15000]	金额(仅支持整数)
`reusableStatus`	`Y`	`boolean`	false	false=只能单次收款 true=多次收款
`mchOrderNo`	`Y`	`string(32)`	mch12345	商户订单号（不允许重复）
`expireTime`	`Y`	`long`	3600	过期时间（单位：秒）默认3600秒`不一定有效,部分通道支持`
`notifyUrl`	`Y`	`string(250)`	`https://acb.com/`	回调地址
`nonceStr`	`Y`	`string(32)`	162838128	随机数
`remark`	`Y`	`string(32)`	remark	备注（请使用英文字符或不带重音的西语）
`realName`	`Y`	`string(32)`	Jack	用户姓名
`phone`	`Y`	`string(32)`	+57xxxxxxx	手机号
`email`	`Y`	`string(64)`	`example@maildomain.com`	邮箱，会校验邮箱格式。
`goodsSubject`	`N`	`string(32)`	apple	商户标题
`goodsBody`	`N`	`string(32)`	apple	商品描述

TIP

注意回调地址仅支持https或者http协议的地址，如果地址是IP地址，请务必使用公网IP。

TIP

请注意，目前684180104开头以及6461805201开头的CLABE过期时间为180天，自创建起时间起。（2024年1月26日调整为180天）

TIP

请注意，目前684180104开头以及6461805201开头的Clabe，如果在距离过期时间不足60天时发生了交易，此CLABE会默认续期有效期为180天。（2024年1月30日调整）

HTTP响应体

JSON 示例

json

{
  "msg": "SUCCESS",
  "code": 200,
  "data": {
    "merchantId": "1002001",
    "mchOrderNo": "test2275700811",
    "orderNo": "PAYIN8374561426934530048",
    "bankName": "BBVA Bancomer",
    "reference": "1411217",
    "concept": "33812449733594396233",
    "payCode": "000000000000000001",
    "payUrl": "http://testpaydesk.mxcashypay.com/index.html?PAYIN8374561426934530048",
    "payDeskUrl": "http://testpaydesk.mxcashypay.com/index.html?PAYIN8374561426934530048",
    "amount": "152",
    "orderFee": "1"
  }
}

参数名	类型	说明
`merchantId`	`long`	商户Id
`mchOrderNo`	`string(32)`	商户订单号
`orderNo`	`string(32)`	平台订单号
`amount`	`decimal(20,2)`	金额
`orderFee`	`decimal(20,2)`	手续费
`payCode`	`string(32)`	OXXO 支付码 /SPEI Clabe 账号
`reference`	`string(7)`	交易参考（CIE）
`concept`	`string(40)`	交易概念
`bankName`	`string(32)`	银行名称
`payUrl`	`string(250)`	支付信息页
`payDeskUrl`	`string(250)`	收银台支付地址

TIP

如果您计划自行开发SPEI CLABE还款账号 / OXXO支付码的展示页面，请使用payCode字段。
如果您想使用CashyPay提供的支付信息页面，请使用payUrl字段。

TIP

当payType=69(SPEI Clabe) 时，我们会提供两种不同模式的Clabe收款，二者的区别在于还款时使用的参数不同。同时在限制还款次数，限制还款金额上也有所差异。

Clabe支付和集中式Clabe支付的区别

Clabe支付

此方式每笔订单会给用户创建不同的Clabe账号，但无法校验订单金额，也无法限制还款次数。

还款时用户仅需要使用Clabe账号即可进行转账支付。

集中式Clabe支付

此方式会校验还款金额以及限制还款次数，当金额和订单金额不匹配时，银行会拒绝交易，并自动退款给用户。

还款时用户需要使用以下参数进行转账支付。

payCode Clabe账号
reference 参考编号，不超过7位，用于识别和跟踪交易，在付款页面一般显示为 El número de referencia 或者 Número De Referencia
concept 交易概念，最长40位，用于识别和跟踪交易，如果返回，必须要让用户正确填写。在付款页面一般显示为y el concepto de pago 或者Concepto
bankName 银行名称，一般无需特意填写，输入clabe账号后大多情况下会自动识别。

用户使用集中式`Clabe`付款时的指引

此指引仅在reference，concept，bankName参数存在值时使用。注意示例的参数值，均为沙盒环境的值，实际生产环境请以实际的值为准。

用户使用`BBVA`银行时

1.在Pagar菜单中选择De Servicios选项并输入Número de convenio CIE

Número de convenio CIE 请输入 reference的值（1411217）

2.填写信息

Referencia: 请输入concept的值（33812449733594396233）。
Importe: $ 40.00 MXN
Concepto: remark

用户使用其他银行时

输入转账和付款信息：

Clabe : 输入payCode000000000000000001
Concepto de pago: 输入concept 33812449733594396233
Referencia: 输入 reference ，1411217
Importe: 40.00 MXN

以Santander银行为例

Santander

查询代收订单

HTTP请求信息

TIP

POST baseUrl + /api/payInQuery

HTTP请求头

请求头	必选	值
`Content-Type`	`Y`	`application/json`
`MerchantId`	`Y`	`MerchantId`
`Sign`	`Y`	`Sign`

HTTP请求体

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

TIP

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

HTTP响应体

json

{
  "msg": "SUCCESS",
  "code": 200,
  "data": {
    "merchantId": "100001",
    "mchOrderNo": "M1656752128806",
    "orderNo": "PAYIN8231497473279467520",
    "payType": "1",
    "payCode": "646012000000015887",
    "payUrl": null,
    "payDeskUrl": null,
    "amount": 100.0,
    "patchOrderNo": "PAYIN82xxxxxxxxx",
    "orderType": "PATCH",
    "fee": null,
    "orderStatus": "PAYING",
    "completionTime": null
  }
}

参数名	类型	字段说明
`merchantId`	`int`	商户Id
`mchOrderNo`	`string(32)`	商户订单号
`orderNo`	`string(32)`	平台订单号
`channelOrderNo`	`string(32)`	渠道订单号
`payType`	`string(32)`	请查看代收PayType枚举
`payCode`	`string(32)`	支付码
`payUrl`	`string(250)`	付款二维码
`payDeskUrl`	`string(250)`	收银台地址
`amount`	`decimal(20,2)`	金额
`fee`	`decimal(20,4)`	手续费
`orderStatus`	`string(32)`	订单状态代收订单状态枚举
`completionTime`	`date`	完成时间
`patchOrderNo`	`string(32)`	关联的原订单的平台订单号
`patchMchOrderNo`	`string(32)`	关联的原订单的商户订单号
`orderType`	`string(32)`	API=API接口 MCH=商户后台 DESK=收银台 PATCH=补单

关于`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。

异步回调通知

异步通知请求

TIP

POST : notifyUrl

回调地址由商户提供或透传。

异步通知请求头

HeaderName	Required	Value
`Content-Type`	`Y`	`application/json`
`MerchantId`	`Y`	`MerchantId`
`Sign`	`Y`	`Sign`

异步通知请求体

json

{
  "orderStatus": "SUCCESS",
  "amount": 10000.0,
  "fee": 0,
  "mchOrderNo": "2a6421c4-3758-4d1a-b47e-f7d0e7133f9e",
  "merchantId": "100001",
  "payDeskUrl": null,
  "orderNo": "PAYDESKxxxxxxxxxxx",
  "payUrl": "xxxxxxxxxxxx",
  "patchOrderNo": "PAYIN82xxxxxxxxx",
  "orderType": "PATCH",
  "completionTime": "2022-08-08 08:08:08",
  "nonceStr": "xxxxxxxxxx"
}

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

TIP

fee 和 completionTime 仅在订单成功支付时有值。completionTime的格式为 yyyy-MM-dd HH:mm:ss。
patchMchOrderNo 字段目前仅墨西哥有，其他国家暂不支持。

关于`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次。

创建代收订单 ​

HTTP请求信息 ​

HTTP请求头 ​

HTTP请求体 ​

HTTP响应体 ​

Clabe支付和集中式Clabe支付的区别 ​

Clabe支付 ​

集中式Clabe支付 ​

用户使用集中式Clabe付款时的指引 ​

用户使用BBVA银行时 ​

用户使用其他银行时 ​

查询代收订单 ​

HTTP请求信息 ​

HTTP请求头 ​

HTTP请求体 ​

HTTP响应体 ​

关于orderType为PATCH时的补充说明 ​

异步回调通知 ​

异步通知请求 ​

异步通知请求头 ​

异步通知请求体 ​

关于orderType为PATCH时的补充说明 ​

创建代收订单

HTTP请求信息

HTTP请求头

HTTP请求体

HTTP响应体

Clabe支付和集中式Clabe支付的区别

Clabe支付

集中式Clabe支付

用户使用集中式`Clabe`付款时的指引

用户使用`BBVA`银行时

用户使用其他银行时

查询代收订单

HTTP请求信息

HTTP请求头

HTTP请求体

HTTP响应体

关于`orderType`为`PATCH`时的补充说明

异步回调通知

异步通知请求

异步通知请求头

异步通知请求体

关于`orderType`为`PATCH`时的补充说明