Cashy Docs Center

Create Payin Order

API EndPoint

POST baseUrl + /api/payIn

Request Parameters

Parameter	Required	Type	Description	Example
`currency`	`Y`	`string(32)`	Currency code	`MXN`
`payType`	`Y`	`int`	Pay product type	Payin PayType Enum
`amount`	`Y`	`decimal(20,0)`	Amount	[40,15000]
`reusableStatus`	`Y`	`boolean`	Multiple payments	false=只能单次收款 true=多次收款
`mchOrderNo`	`Y`	`string(32)`	Merchant order number	mch12345
`expireTime`	`Y`	`long`	Expire time	3600
`notifyUrl`	`Y`	`string(250)`	Webhooks url
`nonceStr`	`Y`	`string(32)`	Random string
`remark`	`Y`	`string(32)`	Remark	Please use English characters or unaccented Spanish
`realName`	`Y`	`string(64)`	User Name
`phone`	`N`	`string(32)`	User phone number
`email`	`N`	`string(64)`	User email

TIP

Please note that the current CLABEs starting with 684180104 and 6461805201 have an expiration date of 180 days from the time of creation. (Adjusted to 180 days on January 26, 2024)

TIP

Please note that the current CLABEs starting with 684180104 and 6461805201, if a transaction occurs within 60 days of the expiration date, the CLABE will be renewed for 180 days by default. (Adjusted on January 30, 2024)

Request Example

bash

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

Response Parameters

Parameter	Type	Description
`merchantId`	`long`	MerchantId
`mchOrderNo`	`string(32)`	Merchant order number
`orderNo`	`string(32)`	Platform order number
`amount`	`decimal(20,2)`	Amount
`orderFee`	`decimal(20,2)`	fee
`payCode`	`string(32)`	OXXO Paycode / SPEI Clabe Account
`reference`	`string(7)`	reference（CIE）
`concept`	`string(40)`	concept
`bankName`	`string(32)`	bankName
`payUrl`	`string(250)`	QR link
`payDeskUrl`	`string(250)`	Payment Url

Response Example

SuccessSome Error

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

If you plan to develop the display page of SPEI CLABE repayment account / OXXO payment code by yourself, please use the payCode field.
If you want to use the payment information page provided by CashyPay, please use the payUrl field.

TIP

When payType=69(SPEI Clabe) , we will provide two different modes of Clabe collection. The difference between the two is that the parameters used when repaying are different. At the same time, there are differences in limiting the number of repayments and the amount of repayments.

The difference between Clabe payment and centralized Clabe payment

Clabe payment

This method will create a different Clabe account for the user for each order, but it cannot verify the order amount or limit the number of repayments.

When repaying, the user only needs to use the Clabe account to transfer and pay.

Centralized Clabe payment

This method will verify the repayment amount and limit the number of repayments. When the amount does not match the order amount, the bank will reject the transaction and automatically refund the user.

When repaying, users need to use the following parameters to transfer and pay.

payCode Clabe account number
reference Reference number, no more than 7 digits, used to identify and track transactions, generally displayed as El número de referencia or Número De Referencia on the payment page
concept Transaction concept, up to 40 digits, used to identify and track transactions. If returned, users must fill it out correctly. Generally displayed as y el concepto de pago or Concepto on the payment page
bankName Bank name, generally no need to fill in specifically, in most cases it will be automatically recognized after entering the clabe account number.

User guidance when using centralized `Clabe` payment

This guidance is only used when the reference, concept, and bankName parameters have values. Note that the parameter values in the examples are all values in the sandbox environment. Please refer to the actual values in the actual production environment.

When using the `BBVA` bank

Select the De Servicios option in the Pagar menu and enter Número de convenio CIE

For Número de convenio CIE, please enter the value of reference (1411217)

Fill in the information

Referencia: Please enter the value of concept (33812449733594396233).
Importe: $ 40.00 MXN
Concepto: remark

When users use other banks

Enter transfer and payment information:

Clabe: Enter payCode000000000000000001
Concepto de pago: Enter concept 33812449733594396233
Referencia: Enter reference, 1411217
Importe: 40.00 MXN

Take Santander Bank as an example

Query Payin Order

API EndPoint

POST baseUrl + /api/payInQuery

Request Parameters

Parameter	Required	Type	Example	Description
`mchOrderNo`	`N`	`string(32)`	1386556575370063873	Merchant order number
`orderNo`	`N`	`string(32)`	PAYIN8551843837024997376	Platform order number
`nonceStr`	`Y`	`string(32)`	9459931608	Random string

TIP

We recommend using orderNo (platform order number) first. At least one of the platform order number and the merchant order number must be passed.

Request Example

bash

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

Response Parameters

Parameter	Type	Description
`merchantId`	`int`	Merchant id
`mchOrderNo`	`string(32)`	Merchant order number
`orderNo`	`string(32)`	Platform order number
`channelOrderNo`	`string(32)`	Channel order number
`payType`	`string(32)`	Payin PayType Enum
`payCode`	`string(32)`	Payment Code
`payUrl`	`string(250)`	Payment url
`amount`	`decimal(20,0)`	Amount
`fee`	`decimal(20,4)`	Fee
`orderStatus`	`string(32)`	Payin Order Status Enum
`completionTime`	`yyyy-MM-dd HH:mm:ss`	Completion time

Response Example

PayingSuccess

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

Async Webhook Notification

The webhooks url is provided by the merchant

POST Merchant NotifyUrl

Webhook Request Parameters

Parameter	Type	Description
`merchantId`	`int`	Merchant id
`mchOrderNo`	`string(32)`	Merchant order number
`orderNo`	`string(32)`	Platform order number
`amount`	`decimal(20,2)`	Amount
`fee`	`decimal(20,4)`	Fee
`orderStatus`	`string(32)`	Order status
`payUrl`	`string(32)`	Payment url
`payCode`	`string(32)`	Payment VA/QRCODE
`payType`	`string(32)`	Pay product type
`completionTime`	`yyyy-MM-dd HH:mm:ss`	Completion time
`nonceStr`	`string(32)`	Random string

Webhook Request Example

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

Webhooks-SuccessWebhooks-Fail

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

When the webhooks response HTTP status code is 200, 301 or 302, we believe that the merchant has successfully received and processed the callback. For other statuses, we believe that the merchant has failed to process the callback.

After the webhooks fails, it will be retried in 1, 2, 4, 8, 16, 32, 64, 128, 256, 512 minutes, and the webhooks will be retried 10 times in total

Create Payin Order ​

The difference between Clabe payment and centralized Clabe payment ​

Clabe payment ​

Centralized Clabe payment ​

User guidance when using centralized Clabe payment ​

When using the BBVA bank ​

When users use other banks ​

Query Payin Order ​

Async Webhook Notification ​

Create Payin Order

The difference between Clabe payment and centralized Clabe payment

Clabe payment

Centralized Clabe payment

User guidance when using centralized `Clabe` payment

When using the `BBVA` bank

When users use other banks

Query Payin Order

Async Webhook Notification