Sandbox Testing

​

What is Sandbox?

• Usa la misma API, misma base URL y los mismos endpoints que producción
• Está conectado a un proveedor bancario simulado (no toca Banxico ni la red SPEI real)
• Las cuentas sandbox son separadas y tienen sus propias credenciales
• Tu código no cambia entre sandbox y producción — solo cambian las credenciales

​

Sandbox vs Production

​

Getting Started with Sandbox

​

Overview

• El header X-Sandbox-Scenario controla el resultado del webhook asíncrono.
• Sin el header, el sandbox devuelve webhooks de éxito por default.
• Para escenarios de error, envía el header explícitamente en la request.
• La feature funciona solo en sandbox — en producción, la request retorna 400.

​

How It Works

​

How to Use

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

​

Available Scenarios

​

Error Scenarios

​

Success Scenario

​

Delay Scenarios

​

Received Webhook Examples

​

Success Webhook (default)

{
  "event": "cash_out",
  "deliveryId": "8e2c5b6f-3a12-4b9c-9a18-77a2b3c4d5e6",
  "createdAt": "2026-03-26T10:00:00.000Z",
  "transaction": {
    "id": 12345,
    "externalId": "test-success-001",
    "paymentMethod": "SPEI",
    "direction": "out",
    "type": "cash_out",
    "status": "CONFIRMED",
    "provider": "sandbox",
    "amountCentavos": 15000,
    "clabe": "012180001234567890",
    "referenceNumerical": "9876543",
    "createdAt": "2026-03-26T09:59:59.000Z",
    "confirmedAt": "2026-03-26T10:00:00.000Z",
    "counterpart": {
      "name": "Maria Lopez",
      "taxId": null,
      "bank": {}
    }
  },
  "errorCode": null,
  "errorMessage": null,
  "metadata": {}
}

​

Error Webhook (error:insufficient-funds)

{
  "event": "cash_out",
  "deliveryId": "1a3f9e8d-2c47-4b9c-aa18-77a2b3c4d5e6",
  "createdAt": "2026-03-26T10:01:00.000Z",
  "transaction": {
    "id": 12346,
    "externalId": "test-error-001",
    "paymentMethod": "SPEI",
    "direction": "out",
    "type": "cash_out",
    "status": "FAILED",
    "provider": "sandbox",
    "amountCentavos": 15000,
    "clabe": "012180001234567890",
    "referenceNumerical": null,
    "createdAt": "2026-03-26T10:00:59.000Z",
    "confirmedAt": null,
    "counterpart": {
      "name": null,
      "taxId": null,
      "bank": {}
    }
  },
  "errorCode": "INSUFFICIENT_FUNDS",
  "errorMessage": "Cuenta sin saldo suficiente",
  "metadata": {}
}

• En status: FAILED, referenceNumerical y confirmedAt son null (la red SPEI nunca confirmó la transacción).
• errorCode y errorMessage describen el motivo de la falla.

​

Compatible Endpoints

​

Behavior

• La API procesa la request normalmente: retorna 201 Created con status: PENDING.
• El header no altera la respuesta inmediata.
• Tras ~1 segundo (o más con delayed:), el webhook es enviado a la URL configurada.
• Tu sistema recibe el webhook con status correspondiente al scenario (CONFIRMED o FAILED).

​

Restrictions

• X-Sandbox-Scenario funciona exclusivamente con cuentas configuradas en modo sandbox.
• Cuentas de producción que envíen el header reciben:

{
  "statusCode": 400,
  "message": "X-Sandbox-Scenario header is only supported in sandbox mode. This account is not configured with a sandbox provider."
}

​

Best Practices

1. Prueba todos los escenarios — implementa el manejo de CONFIRMED, PENDING, FAILED y EXPIRED antes de ir a producción.
2. Valida los campos de error — usa errorCode y errorMessage para tomar la acción adecuada (notificar usuario, retry, etc.).
3. Prueba con delay — verifica que tu sistema maneja bien la entrega lenta del webhook.
4. Idempotencia — usa transaction.id como llave de idempotencia; el mismo webhook puede ser reenviado.