Cashy 文档中心

简体中文

English

简体中文

English

Appearance

创建代收订单 ​

API EndPoint

POST baseUrl + /api/payIn

请求参数

参数名必选类型字段说明示例值
currencyYstring(32)货币代码MXN
payTypeYint代收产品类型代收PayType枚举
amountYdecimal(20,0)金额[40,15000]
reusableStatusYboolean是否允许多次支付false=只能单次收款 true=多次收款
mchOrderNoYstring(32)商户订单号mch12345
expireTimeYlong过期时间3600
notifyUrlYstring(250)回调地址https://merchant.com/webhooks
nonceStrYstring(32)随机字符串1863484722378907648
remarkYstring(32)备注请使用英文字符或不带重音的西语
realNameYstring(32)用户姓名Jack
phoneYstring(32)手机号+57xxxxxxx
emailYstring(64)邮箱 ，会校验邮箱格式。example@maildomain.com

TIP

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

TIP

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

请求示例

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

响应参数

参数名类型说明
merchantIdlong商户Id
mchOrderNostring(32)商户订单号
orderNostring(32)平台订单号
amountdecimal(20,2)金额
orderFeedecimal(20,2)手续费
payCodestring(32)OXXO 支付码 /SPEI Clabe 账号
referencestring(7)交易参考（CIE）
conceptstring(40)交易概念
bankNamestring(32)银行名称
payUrlstring(250)支付信息页
payDeskUrlstring(250)收银台支付地址

响应示例

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"
  }
}
json
{
  "msg": "Payin_Order_Error",
  "code": 500
}

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

查询代收订单 ​

API EndPoint

POST baseUrl + /api/payInQuery

请求参数

参数名必选类型示例值字段说明
mchOrderNoNstring(32)1386556575370063873商户订单号
orderNoNstring(32)PAYIN8551843837024997376平台订单号
nonceStrYstring(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"}'

响应参数

参数名类型字段说明
merchantIdint商户Id
mchOrderNostring(32)商户订单号
orderNostring(32)平台订单号
channelOrderNostring(32)渠道订单号
payTypestring(32)代收PayType枚举
payCodestring(32)支付码
payUrlstring(250)付款二维码
amountdecimal(20,0)金额
feedecimal(20,4)手续费
orderStatusstring(32)代收订单状态枚举
completionTimedate完成时间

响应示例

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

异步通知请求参数

参数名类型说明
merchantIdint商户Id
mchOrderNostring(32)商户订单号
orderNostring(32)平台订单号
amountdecimal(20,2)金额
feedecimal(20,4)手续费
payUrlstring(32)收银台Url
payDeskUrlstring(250)收银台地址
payTypestring(32)代收PayType枚举
orderStatusstring(32)代收订单状态枚举
completionTimedate完成时间
nonceStrstring(32)随机字符串
patchOrderNostring(32)关联的原订单的平台订单号
patchMchOrderNostring(32)关联的原订单的商户订单号
orderTypestring(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"}'
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 末尾会增加序列号标识，用于区分多笔部分还款的订单。

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

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

订单的orderType为API时:

  • patchOrderNo 和orderNo相同
  • patchMchOrderNo 和mchOrderNo相同

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

TIP

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

Released under the MIT License.

Copyright © 2021-Present CashyPay