Create Payin Order

HTTP Request

TIP

POST baseUrl + /api/payIn

Request Headers

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

RequestBody

Parameter	Required	Type	Example	Description
currency	Y	string(32)	MXN	Currency code
payType	Y	int	69	pls refer to Payin PayType Enum
amount	Y	decimal(20,0)	[40,15000]	Amount(Only support integer)
reusableStatus	Y	boolean	false	Currently it can only be false
mchOrderNo	Y	string(32)	mch12345	Merchant order number (should be unique in the merchant system)
expireTime	Y	long	3600	Expiration time, default 3600 seconds
notifyUrl	Y	string(250)	https://acb.com/	webhooks (callback) address
nonceStr	Y	string(32)	162838128	Random string
remark	Y	string(32)	remark	Order remarks
realName	Y	string(32)	Jack	Payer Name
phone	Y	string(32)	+57xxxxxxx	Payer phonenumber
email	Y	string(32)	xyz@gamil.com	Payer email
goodsSubject	N	string(32)	apple	Product subject
goodsBody	N	string(32)	apple	Product description

TIP

Note that the callback address only supports https or http protocol addresses, if the address is an IP address, be sure to use a public IP.

TIP

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

TIP

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

ResponseBody

ResponseBody JSON example

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

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

TIP

When payType=69(SPEI Clabe) is used, we will provide two different modes of Clabe collection, the difference between the two is the different parameters used for repayment. There is also a difference in the number of times you can limit the repayment and the amount you can limit the repayment.

Difference between Clabe Payments and Centralized Clabe Payments

Clabe Payments（SPEI Transfer）

This method creates a different Clabe account for each order, but it is not possible to check the amount of the order or to limit the number of repayments.

To make a payment, the user only needs to use the Clabe account number to make the transfer.

Centralized Clabe Payments（The type will not be returned for the time being）

This method checks the repayment amount as well as limits the number of repayments. When the amount does not match the order amount, the bank will reject the transaction and refund the user automatically.

For repayment the user needs to transfer the payment using the following parameters.

• payCode Clabe account number
• reference The reference number, not exceeding 7 digits, which is used to identify and track the transaction, and is usually shown on the payment page as El número de referencia or Número De Referencia.
• concept The transaction concept, up to 40 digits long, is used to identify and track the transaction, and if returned, must be filled in correctly by the user. On the payment page it is usually displayed as y el concepto de pagoorConcepto`.
• bankName The name of the bank, which is usually not required, and in most cases will be recognized automatically when the clabe account number is entered.

Guidelines for users when using centralized `Clabe' payments

This guideline is only used when the reference, concept, bankName parameters have values. Note that the values of the parameters in the examples are the values in the sandbox environment, please refer to the actual values in the production environment.

When a user uses the `BBVA' bank

1. Select the De Servicios' option in thePagar' menu and enter Número de convenio CIE.

For Número de convenio CIE, 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

Banco Santander as an example

Query Payin Order

HTTP Request

TIP

POST baseUrl + /api/payInQuery

Request Headers

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

RequestBody

Parameter	Required	Type	Example	Description
mchOrderNo	N	string(32)	P123456	Merchant order number
orderNo	N	string(32)	PAYIN12345	Platform order number
nonceStr	Y	string(32)	1628381288000	Random string

TIP

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

ResponseBody

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

Parameter	Type	Description
merchantId	int	MerchantId
mchOrderNo	string(32)	Merchant order number
orderNo	string(32)	Platform order number
channelOrderNo	string(32)	Channel order number
payType	string(32)	pls refer to Payin PayType Enum
payCode	string(32)	支付码
payUrl	string(250)	Payment QR Code
payDeskUrl	string(250)	PayDesk Payment Url
amount	decimal(20,2)	Amount
fee	decimal(20,4)	fee
orderStatus	string(32)	Order StatusPayin Order Status Enum
completionTime	date	Complete timeyyyy-MM-dd HH:mm:ss
patchOrderNo	string(32)	The platform orderNo associated with the replenishment order
patchMchOrderNo	string(32)	The platform mchOrderNoassociated with the replenishment order
orderType	string(32)	API=API接口 MCH=商户后台 DESK=收银台 PATCH=补单

关于orderType为PATCH时的补充说明

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

• orderNo is the newly generated platform order number 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 (with serial number identification) of the associated original order. Note that a serial number identifier will be added at the end of the mchOrderNo returned by the callback to distinguish multiple partial repayment orders.

For example, your merchant order number is MCH20230088. When the first partial payment occurs, we will add the serial number 00001 to the end of the merchant order number mchOrderNo of the original order. , the mchOrderNo of the callback you receive is MCH2023008800001, and so on.

When an order replenishment 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

The above parameters have no additional meaning at this time.

TIP

fee and completionTime only have a value if the order is successfully paid.

Async Webhook Notification

HTTP Request

TIP

POST : notifyUrlnotifyUrlis provided by the merchant

Request Headers

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

Webhook RequestBody

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

Parameter	Type	Description
merchantId	int	MerchantId
mchOrderNo	string(32)	Merchant order number
orderNo	string(32)	Platform order number
amount	decimal(20,2)	Amount
fee	decimal(20,4)	fee
payUrl	string(32)	Payment Url
payDeskUrl	string(250)	PayDesk Payment Url
orderStatus	string(32)	订单状态,pls refer toPayin Order Status Enum
completionTime	date	Complete time
nonceStr	string(32)	Random string
patchOrderNo	string(32)	The platform orderNo associated with the replenishment order
patchMchOrderNo	string(32)	The platform mchOrderNoassociated with the replenishment order
orderType	string(32)	API=API接口 MCH=商户后台 DESK=收银台 PATCH=补单

TIP

fee and completionTime only have a value if the order is successfully paid.

关于orderType为PATCH时的补充说明

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

• orderNo is the newly generated platform order number 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 (with serial number identification) of the associated original order. Note that a serial number identifier will be added at the end of the mchOrderNo returned by the callback to distinguish multiple partial repayment orders.

For example, your merchant order number is MCH20230088. When the first partial payment occurs, we will add the serial number 00001 to the end of the merchant order number mchOrderNo of the original order. , the mchOrderNo of the callback you receive is MCH2023008800001, and so on.

When an order replenishment 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

The above parameters have no additional meaning at this time.

TIP

Please respond with SUCCESS if the process is successful. For other responses, we will consider the callback to have failed. After the callback fails, it will be retried in 1, 2, 4, 8, 16, 32, 64, 128, 256, 512 minutes, and the callback will be retried 10 times in total.