Skip to main content

Pay-in collection

About 4 min

Mexico region pay-in API (MXN). See Payment methods.

Request

POST/v2.0/transaction/pay-in

Request Path:

sandbox: https://sandbox-gateway.smilepayz.com/v2.0/transaction/pay-in
production: https://gateway.smilepayz.com/v2.0/transaction/pay-in

Header Parameters

FieldRequiredTypeDescription
Content-TypeMStringapplication/json request body.
X-TIMESTAMPMStringFormat: yyyy-MM-ddTHH:mm:ss±HH:mm (e.g. Mexico CST −06:00).
X-SIGNATUREMStringSignature of JSON body (see product Signature doc).
X-PARTNER-IDMStringYour merchantID

Body Parameters

FieldRequiredTypeDescription
orderNoMString(32)Merchant-unique id
purposeMString(64)Memo to payer
merchantMObjectWraps merchantId and optional sub-merchant fields.
    merchantIdMStringSmilepayz merchantId for this call.
    merchantNameOStringMerchant display name.
    subMerchantIdOStringSub-merchant ID.
    subMerchantNameOStringName for subMerchantId.
moneyMObjectCurrency plus amount for this transaction.
    currencyMStringFixed to MXN.
    amountMNumberAmount (up to 2 decimal places). See Money
paymentMethodMStringSee Payment methods doc.
expiryPeriodONumberExpiryPeriod, default 3600.
redirectUrlOString(256)HTTPS post-pay return URL, max 256 chars.
callbackUrlOString(256)HTTPS async status URL, max 256 chars.

Example Body – Transaction Request:

Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00-06:00
X-SIGNATURE: 7MHd9v5/m9JeqmDZVwWBZUZ5J5...7120QnFEny7Qm7uQR1G0TWCh10fsU6nVxiRoeoQ==
X-PARTNER-ID: 20001

Responses

HTTP Request

FieldRequiredTypeDescription
Content-TypeMStringapplication/json request body.
X-TIMESTAMPMStringFormat: yyyy-MM-ddTHH:mm:ss±HH:mm

Body Parameters

FieldRequiredTypeDescription
codeMString00 success, other values error.
messageMStringUTF-8 human-readable result line.
orderNoMStringMerchant-unique id
tradeNoOStringSmilepayz tradeNo for this order.
merchantMObjectWraps merchantId and optional sub-merchant fields.
    merchantIdMStringSmilepayz merchantId for this call.
    merchantNameOStringMerchant display name.
    subMerchantIdOStringSub-merchant ID.
    subMerchantNameOStringName for subMerchantId.
moneyMObjectCurrency plus amount for this transaction.
    currencyMStringFixed to MXN.
    amountMNumberAmount (up to 2 decimal places). See Money
transactionTimeMStringyyyy-MM-ddTHH:mm:ss±HH:mm
channelMObjectChannel payload (paymentUrl, qrString, …).
    paymentMethodMStringSee Payment methods doc.
    paymentUrlOStringCashier URL to open for the payer.
    qrStringOStringPIX or channel copy-paste string if returned.
    receiverBankNameOStringBank / brand code when returned.
    vaNumberOStringVirtual account / reference when returned.
statusOStringOrder or payment status enum value.
responseCodeOStringChannel result code when returned (e.g. CODI / OXXO).
responseMessageOStringChannel result text when returned.
Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00-06:00

Sub-order transaction & callback

For Mexico pay-in (e.g. SPEI), the channel may credit the same merchant order more than once. Platform rules:

  1. Create request creates only the main order: /v1/pay does not pre-split sub-orders.
  2. Extra successful credits become sub-orders: each recognized extra credit gets its own tradeNo, credited amount, fees, settlement, and merchant callback.
  3. Callback field meaning:
    • orderNo: always the original merchant order number (same as the main order).
    • tradeNo: platform id for this transaction (main or sub-order; each is unique).
    • money.amount: amount for this credit (a sub-order amount may differ from the original request amount).
  4. Idempotency: you may receive multiple SUCCESS callbacks for one orderNo. Use tradeNo as the transaction-level idempotency key; do not dedupe only by orderNo.
  5. Main and sub-orders are independent: sub-order amounts do not auto-mark the main order SUCCESS or rewrite the main order amount/status. See subOrderList in Inquiry Status.

Tips

Verify signature and return plain-text SUCCESS for every main / sub-order callback.

Notification/Callback

Callback signature ≠ request signature

Do not verify callback X-SIGNATURE with the request-signing formula. See Callback Signature.

HTTP Request

FieldRequiredTypeDescription
Content-TypeMStringapplication/json request body.
X-TIMESTAMPMStringFormat: yyyy-MM-ddTHH:mm:ss±HH:mm
X-SIGNATUREMStringSee Callback Signature

Body Parameters

FieldRequiredTypeDescription
orderNoMStringMerchant-unique id. Main and sub-order callbacks share the same original merchant orderNo.
tradeNoMStringSmilepayz tradeNo for this transaction (main or sub-order). Use this field for transaction-level idempotency.
merchantIdMStringSmilepayz merchantId for this call.
merchantNameMStringMerchant display name.
subMerchantIdOStringSub-merchant ID.
subMerchantNameOStringName for subMerchantId.
paymentMethodMStringSee Payment methods doc.
transactionTimeMStringFormat: yyyy-MM-ddTHH:mm:ss
statusMStringOrder or payment status enum value.
moneyMObjectCurrency plus amount for this transaction.
    currencyMStringFixed to MXN.
    amountMNumberAmount for this credit (up to 2 decimal places). Sub-order uses the actual credited amount. See Money
payerOObjectPayer object per region rules (see Payer model).
    nameOStringBeneficiary full name (UTF-8).

Return

Important

Respond with the string SUCCESS only.

{
    "orderNo": "20001mxspei394eeb7b44c2460",
    "tradeNo": "141200112412131711531135",
    "merchantId": "20001",
    "merchantName": "Smilepayz Demo Store",
    "subMerchantId": "",
    "subMerchantName": "",
    "paymentMethod": "SPEI",
    "transactionTime": "2024-12-13T04:11:54-06:00",
    "status": "SUCCESS",
    "money": {
        "currency": "MXN",
        "amount": 250000
    },
    "payer": {
        "name": "Juan Carlos Hernández"
    }
}
Copyright © 2026 smilepayz teams