← Volver al índice de esquemas

`ValidationRequest`

Cuerpo de `POST /v1/validate` para una validación manual SPEI; exige `clave_rastreo` o `referencia_numerica`, y una sola de las dos formas de indicar la cuenta: `cuenta_beneficiaria` o `cuentas_candidatas`.

Propiedades

Campo	Tipo	Descripción
`fecha`*	`string (date)`	Fecha de envío de la transferencia en formato ISO 8601 (YYYY-MM-DD). Con ella Banxico localiza el CEP, y puede diferir del día de operación que el CEP imprime (`banxico_result.operationDate`).
`monto`*	`number (double)`	Importe de la transferencia (en pesos mexicanos — MXN), mayor que cero y con hasta dos decimales. No se acepta en notación científica (por ejemplo `1e-5`) cuando se envía como texto.
`clave_rastreo`	`string`	Clave de rastreo de la transferencia (entre 1 a 30 caracteres). Acepta letras, números, espacios y los signos de puntuación que admite Banxico (como guiones, diagonales, puntos, comas, `#`, `@` o `_`), pero no `<`, `>` ni la barra invertida. Se recorta y se le quitan caracteres invisibles de ancho cero antes de validarse, para que la misma clave copiada y pegada compare igual en toda la plataforma. Requerida si `referencia_numerica` no es enviada. Si vienen las dos, la consulta a Banxico se hace sólo por la clave.
`referencia_numerica`	`string`	Referencia numérica de la transferencia (entre 1 y 7 dígitos). Acepta solo números y espacios. Requerida si `clave_rastreo` no es enviada. Si viene `clave_rastreo`, la consulta se hace sólo por la clave, y una referencia mal formada no se rechaza: se ignora y se deja un aviso.
`emisor`	`string`	Nombre o código SPEI del banco emisor. Cuando falta o es incorrecto, la clave de rastreo puede aportarlo. Si aun así no puede resolverse, la respuesta es un estado HTTP `422`.
`receptor`	`string`	Nombre / código SPEI del banco receptor. Es opcional cuando el banco puede identificarse a partir de `cuenta_beneficiaria`. Si no puede resolverse, la respuesta será un estado HTTP `422`.
`cuenta_beneficiaria`	`string`	Cuenta bancaria receptora de la transferencia. Es obligatoria cuando no se envía `cuentas_candidatas`: si faltan las dos, la respuesta es un estado HTTP `422` (con `preflight_failed` y el error de campo `cuenta_required`); si vienen las dos, un `422` con `cuenta_y_candidatas_excluyentes`. Puede ser CLABE (18 dígitos), tarjeta (16 dígitos) o celular DiMo (10 dígitos), y el tipo se identifica por la longitud de sus dígitos. Los espacios y guiones que separan grupos ("0121 8000 4412 345678") se ignoran automáticamente antes de contar la longitud. Para celular DiMo, si el banco receptor no puede resolverse por el campo `receptor`, por los beneficiarios registrados ni por el directorio de cuentas, la respuesta es un estado HTTP `422` (con `bank_code_unresolvable_for_phone` en el cuerpo).
`cuentas_candidatas`	`array`	Cuentas entre las que está la receptora de la transferencia, para cuando no se sabe cuál fue. Va en lugar de `cuenta_beneficiaria`: enviar las dos responde un estado HTTP `422` (con `cuenta_y_candidatas_excluyentes` en el cuerpo). Admite de 2 al máximo vigente de la plataforma, 3 por defecto y nunca más de 10; el `422` por exceso informa el máximo en `meta.max`. Cada cuenta es una CLABE (18 dígitos), una tarjeta (16) o un celular DiMo (10), con su dígito verificador válido y sin repetirse. Una lista que no cumple responde un `422` con `cuentas_candidatas_invalidas`, y señala en `field_errors` la posición que falló. Los dos errores ocurren antes de consumir cuota. Consume una sola unidad de cuota, lleve las cuentas que lleve. La consulta recorre las candidatas en el orden enviado y adopta la primera que coincide con la transferencia. La ganadora se publica completa en `normalized_data.cuenta_beneficiaria`, y `candidate_match` indica su posición. Si ninguna coincide, la respuesta es un estado HTTP `422` con el motivo en `code` (`cuenta_unresolvable_after_probes` cuando no hay un diagnóstico más preciso).
`receptor_participante`	`integer`	Indica si el beneficiario de la transferencia es directamente la institución receptora del pago («Pago a Banco» en el CEP de Banxico) y no uno de sus cuentahabientes. `0` para una transferencia a un cuentahabiente (valor por defecto); `1` para pagos cuyo beneficiario es el banco —pago de tarjeta de crédito, de crédito o de servicios a la propia institución. Opcional: si se omite se asume `0`.
`retry_policy`	`object`	Política de reintentos automáticos para esta validación. Si se omite, se aplica la política general configurada para el usuario. Los reintentos NO consumen cuota de validaciones.
`enabled`	`boolean`	`true` cuando el ciclo de reintentos está activo. Si es `false`, los demás campos pueden ser ignorados.
`max_retries`	`integer`	Número máximo de reintentos automáticos. Una vez alcanzado, el ciclo pasa al estado terminal `exhausted`.
`interval_seconds`	`integer`	Segundos de espera entre cada reintento. Valores válidos: 300–86400 (5 min a 24h).
`outcomes`	`array`	Resultados que originan un reintento. De forma predeterminada son `not_found`, `cep_unavailable` y `error`; la combinación `["not_found", "cep_unavailable"]` excluye `error`.
`client_ref`	`string`	Referencia propia que se devuelve tal cual en la validación, en los webhooks de validación y como filtro exacto de `GET /v1/validations`. Texto de 1 a 64 caracteres, sin saltos de línea ni emoji; se recorta antes de guardarse. Un valor que no cumple se rechaza con un estado HTTP `422` (con `invalid_client_ref` en el cuerpo). No debe contener datos personales.

Variantes

Debe incluir al menos uno de estos campos:

clave_rastreo
referencia_numerica

Usado en operaciones

POST /v1/validate