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

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

Success

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

Some Error

{
  "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

1. 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)

2. 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

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)	Order StatusPayin Order Status Enum
completionTime	yyyy-MM-dd HH:mm:ss	Complete time

Response Example

Success

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

Payment in progress

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

Supplementary instructions when orderType is PATCH

If the user does not pay according to the order amount or pays repeatedly, a supplementary order will appear. In this case, the orderType of the supplementary order is PATCH:

• orderNo is the platform order number newly generated for this order.
• patchOrderNo is the platform order number of the associated original order,
• patchMchOrderNo is the merchant order number of the associated original order.
• mchOrderNo is the merchant order number of the associated original order (with a serial number identifier). Note that at this time, the serial number identifier will be added to the end of the mchOrderNo returned by the callback to distinguish multiple partial repayment orders.

For example, if your merchant order number is MCH20230088, when the first partial payment is generated, we will add the serial number 00001 to the end of the merchant order number mchOrderNo of the original order.

The mchOrderNo you receive in the callback is MCH2023008800001, and so on.

When a patch order occurs, our robot will also notify the corresponding merchant group, and the notification will contain all the information you need.

When the orderType of the order is API:

• patchOrderNo is the same as orderNo
• patchMchOrderNo is the same as mchOrderNo

At this time, the above parameters have no additional meaning.

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

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

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

Webhooks-Fail

{
  "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