Pay-In · Mexico

Overview

The Pay-In API initiates collection transactions from customers. This page covers Mexico (country code mx) with two ordering modes:

Mode	Path	Description
Cashier mode	/pay/prePay	Default. Returns cashierUrl for the platform H5 cashier
API mode	/pay/transOrder	Requires method in the request; returns payData / payDataType (CLABE, QR code, redirect URL, etc.)

method (Mexico Pay-In codes) is listed in Regional Payment Guide — Mexico.

Integration note

Cashier mode is enabled by default. Contact support to whitelist your merchant account before integrating API mode.

Request Header

Shared by both modes:

Field	Required	Type	Description
Content-Type	M	String	Fixed value: application/json

---

Cashier Mode (prePay)

Pre-order and redirect the customer to the platform cashier via cashierUrl.

Request URL

Domain: Prefer unified host openapi.toppayment.com (path unchanged); legacy country domain (e.g. global-mx-openapi.toppayment.com) remains available.

Environment	URL
Sandbox	https://openapi.toppayment.com/sandbox/mx/pay/prePay
Production	https://openapi.toppayment.com/mx/pay/prePay

Request Body

Field	Required	Type	Description
mchNo	M	String(32)	Merchant number
orderNum	M	String(64)	Merchant order number
amount	M	Number(32,8)	Transaction amount Positive, integer or at most 2 decimal places; not all zeros; no three or more decimal places Example: 100.50
productDetail	M	String(100)	Product detail
method	O	String(16)	Payment method (Mexico) Optional; omit to let the user choose on the cashier. Common: SPEI; also CODI, OXXO — Regional Payment Guide — Mexico
timestamp	M	String(13)	Timestamp in milliseconds
customerName	M	String(64)	Customer name
customerEmail	M	String(64)	Customer email
customerPhone	M	String(32)	Customer phone
expiryPeriod	O	Number(1–9999)	Validity in minutes
downNotifyUrl	M	String(255)	Async callback URL
redirectUrl	O	String(512)	Redirect after payment
sign	M	String	Signature — see Signature

Request Body Example

Content-type: application/json

{
    "mchNo": "{{mchNo}}",
    "orderNum": "MX1234561",
    "amount": 100.50,
    "productDetail": "Product",
    "method": "SPEI",
    "timestamp": "1749451858772",
    "customerName": "Juan Garcia",
    "customerEmail": "[email protected]",
    "customerPhone": "+5255123456789",
    "expiryPeriod": 1440,
    "downNotifyUrl": "https://example.com/notify",
    "redirectUrl": "https://example.com/return",
    "sign": "Generate per signature rules and replace"
}

Response Body Parameters

Field	Required	Type	Description
success	M	Boolean	Success flag
code	M	String	9999 = success
msg	O	String	Message
timeStamp	M	Number	Server time (ms)
data	M	Object	Payload
orderNum	M	String	Merchant order number
platOrderNum	M	String	Platform order number
amount	M	Number	Transaction amount
fee	M	Number	Fee
method	M	String	Payment method — Regional Payment Guide — Mexico
productDetail	M	String	Product detail
customerName	M	String	Customer name
customerEmail	M	String	Customer email
customerPhone	M	String	Customer phone
validTime	M	Number	Expiry timestamp (ms)
cashierUrl	M	String	Cashier URL

Response note

Cashier mode does not return payData or payDataType. Those fields appear only in API mode responses.

Content-type: application/json

{
    "success": true,
    "code": "9999",
    "msg": null,
    "timeStamp": 1767840272829,
    "data": {
        "orderNum": "MX1234561",
        "platOrderNum": "PRE2009093829059153920",
        "amount": 100.50,
        "fee": 2.0,
        "method": "SPEI",
        "productDetail": "Product",
        "customerName": "Juan Garcia",
        "customerEmail": "[email protected]",
        "customerPhone": "+5255123456789",
        "validTime": 1767926672819,
        "cashierUrl": "https://example.cashier/pay"
    }
}

---

API Mode (transOrder)

Specify the payment method in the request, place the order directly with the channel, and receive payData / payDataType (SPEI CLABE, CoDi QR payload, OXXO payment page URL, etc.) without the platform H5 cashier.

Request URL

Environment	URL
Sandbox	https://openapi.toppayment.com/sandbox/mx/pay/transOrder
Production	https://openapi.toppayment.com/mx/pay/transOrder

Request Body

Differences from cashier mode:

Field	Required	Type	Description
method	M	String(16)	Payment method (Mexico) Required in API mode. Common: SPEI, CODI, OXXO — Regional Payment Guide — Mexico

All other fields match cashier mode.

Request Body Example

Content-type: application/json

{
    "mchNo": "{{mchNo}}",
    "orderNum": "MXAPI1234561",
    "amount": 100.50,
    "productDetail": "Product",
    "method": "SPEI",
    "timestamp": "1749451858772",
    "customerName": "Juan Garcia",
    "customerEmail": "[email protected]",
    "customerPhone": "+5255123456789",
    "expiryPeriod": 1440,
    "downNotifyUrl": "https://example.com/notify",
    "sign": "Generate per signature rules and replace"
}

{
    "mchNo": "{{mchNo}}",
    "orderNum": "MXAPI7890121",
    "amount": 100.50,
    "productDetail": "Product",
    "method": "CODI",
    "timestamp": "1749451858772",
    "customerName": "Juan Garcia",
    "customerEmail": "[email protected]",
    "customerPhone": "+5255123456789",
    "expiryPeriod": 1440,
    "downNotifyUrl": "https://example.com/notify",
    "sign": "Generate per signature rules and replace"
}

Response Body Parameters

Common fields match cashier mode. API mode focuses on:

Field	Required	Type	Description
payData	M	String	Payment payload — CLABE, CoDi QR string, OXXO page URL, etc.; meaning depends on payDataType
payDataType	M	String	VA, QR_CODE, CASHIER_URL, etc.

payDataType Reference

payDataType	Description	Typical methods
VA	Virtual account / CLABE for bank transfer	SPEI
QR_CODE	QR payload string — render as QR code on your side	CODI
CASHIER_URL	Upstream payment page URL	OXXO

Content-type: application/json

{
    "success": true,
    "code": "9999",
    "msg": null,
    "timeStamp": 1767840272829,
    "data": {
        "orderNum": "MXAPI1234561",
        "platOrderNum": "PRE2009093829059153920",
        "amount": 100.50,
        "fee": 2.0,
        "method": "SPEI",
        "productDetail": "Product",
        "customerName": "Juan Garcia",
        "customerEmail": "[email protected]",
        "customerPhone": "+5255123456789",
        "validTime": 1767926672819,
        "payData": "646180157000000004",
        "payDataType": "VA"
    }
}

{
    "success": true,
    "code": "9999",
    "msg": null,
    "timeStamp": 1767840272829,
    "data": {
        "orderNum": "MXAPI7890121",
        "platOrderNum": "PRE2009093829059153921",
        "amount": 100.50,
        "fee": 2.0,
        "method": "CODI",
        "productDetail": "Product",
        "customerName": "Juan Garcia",
        "customerEmail": "[email protected]",
        "customerPhone": "+5255123456789",
        "validTime": 1767926672819,
        "payData": "00020101021226650016COM.MX.CODI...",
        "payDataType": "QR_CODE"
    }
}

---

Notification

Both ordering modes use the same async callback. Mexico uses v1 only — notifyVersion / v2 payer fields are not supported.

For SPEI and similar flows, multiple success callbacks under the same orderNum are possible — see Pay-In notification rules in Regional Payment Guide — Mexico.

HTTP Request

Field	Required	Type	Description
Content-Type	M	String	application/json

Notification Body

Field	Required	Type	Description
platOrderNum	M	String	Platform order number
version	M	String	Fixed value: v1
orderNum	M	String	Merchant order number
amount	M	Number	Amount
fee	M	Number	Fee
customerName	M	String	Customer name
customerEmail	M	String	Customer email
customerPhone	M	String	Customer phone
status	M	String	Status — see Transaction Status Codes
sign	M	String	Callback signature

Acknowledgment

Important

Return the string SUCCESS only to confirm receipt of the notification.

{
    "platOrderNum": "PRE2009165141186183168",
    "version": "v1",
    "orderNum": "MX12345621",
    "amount": 100.50,
    "fee": 2,
    "customerName": "Juan Garcia",
    "customerEmail": "[email protected]",
    "customerPhone": "+5255123456789",
    "status": "SUCCESS",
    "sign": "…"
}

SUCCESS