SPEI Cash-In

Visión General

El cash-in SPEI genera una CLABE desechable que el pagador usa para hacer una transferencia SPEI desde la app de su banco. Cuando NTX Pay recibe la liquidación, se te notifica en el webhook cash_in con el evento transaction.cash_in.settled. Características:

CLABE válida para una única transferencia (un solo uso)
Confirmación asíncrona (segundos a minutos)
Expira en ~24 horas si no se paga (recibes el webhook transaction.cash_in.expired)

Endpoint

POST /api/spei/cash-in

Headers

Authorization: Bearer {token}
Content-Type: application/json

Request

curl -X POST https://sandbox.mx.ntxpay.com/api/spei/cash-in \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCentavos": 50000,
    "externalId": "order-abc-123",
    "description": "Order #123",
    "customerName": "Juan Perez",
    "customerEmail": "juan@example.com",
    "customerTaxId": "PEPJ800101ABC"
  }'

Response (201)

{
  "transactionId": "3f2a1c34-9d1e-4c7b-8a5e-2b6f0d9c4e71",
  "status": "PENDING",
  "destinationClabe": "012180001234567890",
  "beneficiary": {
    "name": "NTX Pay MX",
    "taxId": "NTX800101ABC"
  },
  "referenceNumerical": "1234567",
  "checkoutUrl": "https://pay.ntxpay.com/checkout/xyz",
  "expiresAt": "2026-05-14T23:59:59.000Z",
  "amountCentavos": 50000
}

Muestra la destinationClabe (y/o la checkoutUrl) al pagador final. El transactionId (UUID) es el identificador único de la transacción — es el mismo valor entregado en los webhooks; úsalo para correlacionar eventos y consultar la transacción.

Campos del Response

string

requerido

Identificador único de la transacción (UUID). Mismo valor entregado en los webhooks.

string

requerido

Estado de la transacción: PENDING, CONFIRMED, FAILED o EXPIRED.

string

requerido

CLABE de destino que el pagador debe usar en la transferencia SPEI.

object

requerido

Beneficiario mostrado al pagador (name y, cuando esté disponible, taxId).

string

Referencia numérica SPEI, cuando esté disponible.

string

URL de checkout alojado (alternativa a la transferencia manual), cuando esté disponible.

string

requerido

Expiración del cobro (ISO 8601).

integer

requerido

Monto en centavos MXN.

Campos del Request

integer

requerido

Monto en centavos MXN. **Mínimo: 1000 centavos (

10.00 MXN)** — piso del banco socio; por debajo la API devuelve `400` con code `CASHIN_MIN_AMOUNT`. Ej.: `50000` =

500.00 MXN.

string

Identificador externo único (hasta 100 caracteres). Úsalo para correlacionar con tu sistema. Recomendado para idempotencia.

string

Descripción del cobro (hasta 255 caracteres).

string

requerido

Nombre del pagador (1–255 caracteres), mostrado en el checkout SPEI.

string

requerido

Correo electrónico del pagador (formato de e-mail válido).

string

RFC/CURP del pagador (10–20 caracteres).

Flujo de Pago

Estados de la Transacción

Status	Significado
`PENDING`	CLABE emitida, en espera de la transferencia
`CONFIRMED`	Transferencia recibida y liquidada
`FAILED`	Error de procesamiento
`EXPIRED`	La CLABE expiró sin recibir la transferencia

En el webhook, la liquidación llega como transaction.cash_in.settled con status: LIQUIDATED — consulta el payload completo.

Idempotencia

Reenvía la misma solicitud con el mismo externalId para garantizar que una falla de red no genere dos cobros. En caso de duplicación, NTX Pay devuelve el cobro existente.

Probar en el Sandbox

En el sandbox, la liquidación se simula en segundos — sin depender de un banco emisor. Controla el desenlace con el header X-Sandbox-Scenario:

curl -X POST https://sandbox.mx.ntxpay.com/api/spei/cash-in \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Sandbox-Scenario: rejected" \
  ...

Consulta el catálogo de escenarios para forzar rechazo, devolución y retraso.

Próximos Pasos

Webhook cash_in

Payload del webhook de confirmación

SPEI Cash-Out

Envía transferencias SPEI

Guía

Sandbox

Webhooks

Autenticación

SPEI

Webhooks Config

Visión General

Endpoint

POST /api/spei/cash-in

Headers

Request

Response (201)

Campos del Response

Campos del Request

Flujo de Pago

Estados de la Transacción

Idempotencia

Probar en el Sandbox

Próximos Pasos

Webhook cash_in

SPEI Cash-Out

​Visión General

​Endpoint

​POST /api/spei/cash-in

​Headers

​Request

​Response (201)

​Campos del Response

​Campos del Request

​Flujo de Pago

​Estados de la Transacción

​Idempotencia

​Probar en el Sandbox

​Próximos Pasos

Webhook cash_in

SPEI Cash-Out

Visión General

Endpoint

POST /api/spei/cash-in

Headers

Request

Response (201)

Campos del Response

Campos del Request

Flujo de Pago

Estados de la Transacción

Idempotencia

Probar en el Sandbox

Próximos Pasos