Escenarios de prueba

Cómo usarlo

Agrega el header X-Sandbox-Scenario: <escenario> a cualquier llamada de cash-in o cash-out. Sin el header, el sandbox usa el escenario success por defecto.

curl -X POST https://sandbox.mx.ntxpay.com/api/spei/cash-out \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Sandbox-Scenario: insufficient_funds" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCentavos": 15000,
    "destinationClabe": "012180001234567890",
    "beneficiaryName": "Maria Lopez"
  }'

La mayoría de los escenarios controla el webhook asíncrono: la respuesta HTTP es 201 Created con status: PENDING, y el resultado final llega en el webhook. Las excepciones son timeout y service_unavailable, que fallan en la respuesta HTTP síncrona.

Escenarios disponibles

Los valores canónicos de escenario son: success, pending_long, rejected, returned, insufficient_funds, bad_clabe, timeout, service_unavailable.

Escenarios de resultado asíncrono

Devuelven 201 PENDING de forma síncrona; el estado final llega vía webhook en segundos.

Header Value	Webhook resultante	Notas
`success` (default)	`*.settled` — `status: LIQUIDATED`	También se usa cuando no se envía ningún header
`pending_long`	`*.settled` — `status: LIQUIDATED` después de ~30s	Prueba la liquidación lenta
`rejected`	`*.rejected` — `status: REJECTED`	La red SPEI rechazó la transferencia
`returned`	`*.returned` — `status: RETURNED`	Aceptada y luego devuelta por la contraparte
`insufficient_funds`	`cash_out.rejected` — `status: REJECTED`	Solo cash-out — simula rechazo por falta de fondos
`bad_clabe`	`cash_out.returned` — `status: RETURNED`	Solo cash-out — aceptada y devuelta por CLABE inválida

Los eventos *.returned se entregan en el webhook del tipo refund_in/refund_out (o all), no en el cash_in/cash_out. Para probar los escenarios returned y bad_clabe, registra también esos webhooks — consulta los tipos de webhook.

Escenarios de error síncrono

Fallan en la propia respuesta HTTP — no se envía ningún webhook.

Header Value	Respuesta síncrona
`timeout`	Timeout en el procesamiento (`504`) después de ~16s
`service_unavailable`	Servicio temporalmente no disponible (`503`)

Restricciones de cash-in: insufficient_funds y bad_clabe no aplican a cash-in (no hay saldo que debitar, y la CLABE de depósito la genera el sistema). Enviar cualquiera de ellos en un cash-in devuelve 400 con código SCENARIO_NOT_APPLICABLE.

Ejemplo: webhook de éxito

Escenario success en un cash-out — el webhook cash_out recibe:

{
  "event": "transaction.cash_out.settled",
  "transactionId": "56789",
  "amount": 15000,
  "currency": "MXN",
  "status": "LIQUIDATED",
  "destinationClabe": "012180001234567890",
  "sourceClabe": null,
  "reference": "9876543",
  "voucher": "CEP20260326G7H8I9",
  "occurredAt": "2026-03-26T10:00:00.000Z"
}

Ejemplo: webhook de rechazo

Escenario insufficient_funds — el webhook cash_out recibe:

{
  "event": "transaction.cash_out.rejected",
  "transactionId": "56790",
  "amount": 15000,
  "currency": "MXN",
  "status": "REJECTED",
  "destinationClabe": "012180001234567890",
  "sourceClabe": null,
  "reference": null,
  "voucher": null,
  "occurredAt": "2026-03-26T10:01:00.000Z"
}

En status: REJECTED, los campos de comprobante (reference, voucher) vienen null — la red SPEI nunca confirmó la transacción. El formato completo del payload está en Visión General de Webhooks.

Restricciones

El header X-Sandbox-Scenario funciona exclusivamente en cuentas sandbox.
Las cuentas de producción que envíen el header reciben:

{
  "statusCode": 400,
  "message": "X-Sandbox-Scenario header is only supported in sandbox mode."
}

Buenas prácticas

Prueba todos los escenarios antes de salir a producción — implementa el manejo de los cuatro status (LIQUIDATED, PENDING, REJECTED, RETURNED).
Enruta por el campo event — *.settled, *.rejected y *.returned exigen acciones diferentes en tu sistema.
Prueba con retraso — usa pending_long para verificar que tu sistema maneja bien la liquidación lenta.
Idempotencia — deduplica por el header x-event-id; el mismo evento puede reentregarse.

Guía

Sandbox

Webhooks

Autenticación

SPEI

Webhooks Config

Cómo usarlo

Escenarios disponibles

Escenarios de resultado asíncrono

Escenarios de error síncrono

Ejemplo: webhook de éxito

Ejemplo: webhook de rechazo

Restricciones

Buenas prácticas

​Cómo usarlo

​Escenarios disponibles

​Escenarios de resultado asíncrono

​Escenarios de error síncrono

​Ejemplo: webhook de éxito

​Ejemplo: webhook de rechazo

​Restricciones

​Buenas prácticas

Cómo usarlo

Escenarios disponibles

Escenarios de resultado asíncrono

Escenarios de error síncrono

Ejemplo: webhook de éxito

Ejemplo: webhook de rechazo

Restricciones

Buenas prácticas