Ir al contenido

Changelog

Cambios que afectan a un comercio integrado con la API de Neat México. La API sigue en v1.

Mientras la API esté en pruebas, v1 puede cambiar y cada cambio se anuncia aquí: si ya estás integrado contra el ambiente de pruebas, esta página es lo que tienes que mirar. Cuando pases a producción te avisamos antes de cualquier cambio incompatible, y a partir de ahí no lo hacemos dentro de la versión que estés usando.

2026-11-05 · un payment.succeeded puede llegar sin sesión ni referencia

Sección titulada «2026-11-05 · un payment.succeeded puede llegar sin sesión ni referencia»

resource.session_id y resource.external_reference de los webhooks pueden venir ahora en null, y las mismas columnas del CSV de conciliación vacías. Pasa cuando un pagador transfiere por SPEI a la CLABE de su unidad un monto que no coincide con ninguna obligación abierta de esa unidad: el dinero se acredita y te avisamos, pero no salda ninguna de tus obligaciones. Si tu integración busca la obligación por external_reference sin revisar que exista, ajústala. Una transferencia por el monto exacto de una obligación abierta la salda como un pago con tarjeta. Ver Pagos sin obligación.

2026-11-05 · unit_id es obligatorio al crear una sesión

Sección titulada «2026-11-05 · unit_id es obligatorio al crear una sesión»

Cambio incompatible. POST /v1/checkout-sessions exige ahora unit_id: tu identificador de la unidad (departamento, lote) que se cobra, como "301" o "Torre B PG-1". Una sesión sin él responde 422 VALIDATION_ERROR con field: "unit_id", también al reintentar con una Idempotency-Key de una sesión creada antes de este cambio: para esos reintentos usa una llave nueva. Es un término inmutable de la obligación, como el monto: reutilizar un external_reference con otro unit_id responde 409 OBLIGATION_CONFLICT. Una referencia creada antes de este cambio toma el unit_id de la primera sesión que lo mande. Manda siempre el mismo valor para la misma unidad, ver Unidad.

2026-10-30 · la tarjeta de prueba aprobada ahora es 4456528080389860

Sección titulada «2026-10-30 · la tarjeta de prueba aprobada ahora es 4456528080389860»

Ningún cambio en la API. Desde el 22 de octubre el checkout verifica con 3D Secure cada tarjeta que se guarda, y en pruebas 5451951574925480 ya no pasa esa verificación: se rechaza al guardarla. Para un pago aprobado usa 4456528080389860 y, cuando el banco de prueba pida el código, escribe 1234. 4349001210846432 tampoco se guarda: el procesador responde que la tarjeta no es compatible, así que ya no sirve para probar un cobro rechazado. Ver Alta de tu comercio.

2026-10-30 · un cobro lento termina con resultado en vez de quedar pending

Sección titulada «2026-10-30 · un cobro lento termina con resultado en vez de quedar pending»

Ningún cambio de forma en la API ni en lo que significa cada evento. Neat espera ahora hasta 20 segundos la respuesta del adquirente a un cobro con tarjeta; antes cortaba a los 9. Un cobro que el adquirente aprueba o rechaza en ese rango, como los de tarjetas con verificación 3D Secure en el ambiente de pruebas, termina en payment.succeeded o payment.failed en vez de payment.pending. Si el adquirente responde con un error o con algo ilegible, el pago sigue quedando payment.pending. Vas a recibir menos payment.pending; los que lleguen se siguen resolviendo como dice la entrada del 23 de octubre.

2026-10-23 · un payment.pending ahora se resuelve

Sección titulada «2026-10-23 · un payment.pending ahora se resuelve»

Ningún cambio de forma en la API. Un pago que quedó pending porque el adquirente no respondió sigue así hasta que alguien de Neat revisa el cargo en la consola del adquirente y registra el resultado; entonces recibes payment.succeeded o payment.failed para el mismo payment_id, con una resource.version mayor. La entrada del 15 de septiembre decía que un payment.pending no tenía continuación: ya no es así. Si tu integración trataba pending como final, trátalo como transitorio y deja que el evento con mayor version mande, ver Webhooks: eventos y firma. Si un cobro lleva horas en pending, escríbenos.

2026-10-22 · tu comercio puede absorber la comisión: fee_bearer

Sección titulada «2026-10-22 · tu comercio puede absorber la comisión: fee_bearer»

Ahora la comisión de Neat la puede pagar tu comercio en vez del pagador. En ese caso el pagador paga exactamente el monto de la obligación, el checkout no le muestra comisión, y la comisión con su IVA se descuenta del depósito. Es un acuerdo comercial que Neat habilita por comercio. Si ya estás integrado no tienes que cambiar nada: mientras no lo acuerdes, el pagador sigue pagando la comisión. Si Neat habilita que tu comercio la absorba como única forma, tus sesiones nuevas la absorben sin cambios, siempre que no mandes fee_bearer. Si habilita las dos, tienes que mandar fee_bearer en cada sesión.

  • Campo nuevo en las respuestas: fee_bearer (payer o provider) en la respuesta de creación, en la sesión (GET /v1/checkout-sessions/{sessionId}), en el pago y en el data de cada webhook. Con provider, provider_fee_minor y provider_fee_tax_minor dejan de ser 0, payer_fee_minor y payer_fee_tax_minor quedan en 0, y provider_net_amount_minor es el monto menos la comisión y su IVA. Los pagos anteriores traen payer en la API, el webhook y el CSV.
  • Columna nueva en el archivo de conciliación: fee_bearer, al final, después de category. Si tu parser exige un número fijo de columnas, actualízalo.
  • Campo nuevo en la creación: fee_bearer. Opcional si tu comercio tiene una sola forma habilitada; obligatorio si tiene las dos, y sin él la respuesta es 422 VALIDATION_ERROR con field: "fee_bearer".
  • Errores nuevos: 422 FEE_BEARER_NOT_ALLOWED si mandas una forma que tu comercio no tiene habilitada, y 422 AMOUNT_BELOW_FEE si tu comercio absorbe la comisión y el monto no deja nada que depositar.
  • No es un término de la obligación: queda fijo en cada sesión y reusar un external_reference con otro fee_bearer no responde 409.

Detalle en Importes y comisiones y en Quién paga la comisión.

2026-10-22 · la sesión dice qué se está pagando: category

Sección titulada «2026-10-22 · la sesión dice qué se está pagando: category»

POST /v1/checkout-sessions acepta category, con tres valores: maintenance_fee (cuota de mantenimiento), rent (renta) y rent_guarantee_insurance (póliza de renta). Con ella cambian el texto del checkout y de los correos al pagador. Si ya estás integrado no tienes que cambiar nada: tu comercio tiene habilitada solo la cuota de mantenimiento, puedes seguir sin mandar el campo y tus reintentos con la misma Idempotency-Key devuelven la misma sesión.

  • Campo nuevo en las respuestas: category en la sesión (GET /v1/checkout-sessions/{sessionId}), en el pago y en el data de cada webhook. En el pago puede ser null solo si su obligación ya no se puede leer.
  • Columna nueva en el archivo de conciliación: category, al final. Si tu parser exige un número fijo de columnas, actualízalo.
  • Error nuevo: 422 CATEGORY_NOT_ALLOWED si mandas una categoría que tu comercio no tiene habilitada. Si tu comercio tiene varias y no mandas category, la respuesta es 422 VALIDATION_ERROR con field: "category".
  • Término de la obligación: reusar un external_reference con otra categoría responde 409 OBLIGATION_CONFLICT, igual que con otro monto.

Detalle en Categoría del cobro.

2026-10-19 · los errores de monto y de Idempotency-Key dicen qué corregir

Sección titulada «2026-10-19 · los errores de monto y de Idempotency-Key dicen qué corregir»

Cambia el texto de cuatro respuestas 422 VALIDATION_ERROR de POST /v1/checkout-sessions. El código, el field y el estado HTTP siguen iguales; si tu integración compara el message exacto, actualízala.

  • Monto bajo tu mínimo: Amount is below the provider minimum of 2000 cents (MXN 20.00)., con el mínimo de tu comercio.
  • Monto sobre tu máximo: Amount exceeds the provider maximum of 5000000 cents (MXN 50,000.00)., con el máximo de tu comercio.
  • Monto que no es un entero positivo: Amount must be a positive integer in cents: MXN 12,850.00 is 1285000.
  • Idempotency-Key ausente o inválida: Idempotency-Key must be 8 to 128 characters from A-Z, a-z, 0-9, '.', '_', ':' and '-'.

Esta documentación ahora muestra la conversión del monto: amount_minor es un entero en centavos, así que MXN 12,850.00 se envía como 1285000, y 12850 son MXN 128.50. Está en el Quickstart, en Sesiones de checkout y en la especificación OpenAPI. Sesiones de checkout también dice ahora el formato de la Idempotency-Key, que antes sólo traía la especificación.

2026-10-14 · el checkout dice para qué cuenta es el cobro

Sección titulada «2026-10-14 · el checkout dice para qué cuenta es el cobro»

Ningún cambio en la API. Quien entra con un correo distinto del payer.email de la sesión ya no ve «Liga de pago no disponible» en rojo: ve «Este pago es para otra cuenta», con el correo con que entró, la dirección del cobro enmascarada, a quién le paga y el monto, y, mientras el cobro sigue pendiente, que no se hizo ningún cargo. El botón lleva a pedir el código para la dirección del cobro. La respuesta sigue siendo 403 PAYER_MISMATCH, y el Quickstart ya lo dice así. Cuando la sesión trae payer.email, la pantalla del código tampoco ofrece «Usar otro correo»: antes aparecía y volvía a la misma dirección.

2026-10-14 · cada error trae un request_id único

Sección titulada «2026-10-14 · cada error trae un request_id único»

El request_id de las respuestas de error ahora es req_ seguido de 32 caracteres hexadecimales y no se repite. Antes era un contador corto, como req-7, que se repetía entre servidores y no alcanzaba para encontrar tu request. Sigue siendo un texto: si lo guardas, no tienes que cambiar nada. Cuando nos escribas por un error, incluye ese valor: con él encontramos tu request en nuestros registros.

2026-10-13 · el checkout pide menos datos al pagador

Sección titulada «2026-10-13 · el checkout pide menos datos al pagador»

Ningún cambio en la API. Antes de guardar la primera tarjeta, el checkout ya no pide fecha de nacimiento, y a quien entró con Google le pide sólo el RFC, porque el nombre ya viene en su cuenta. Cómo pruebas ya lo dice así.

2026-10-13 · correcciones a esta documentación

Sección titulada «2026-10-13 · correcciones a esta documentación»

Ningún cambio en la API. Corregimos lo que llevaba a un primer intento a fallar copiando los ejemplos.

  • Si tu comercio cobra por beneficiario, el Quickstart ahora lo dice. Cada creación tiene que incluir beneficiary o responde 422 BENEFICIARY_REQUIRED. Hay ejemplos completos en cURL, Node y PHP, y la referencia de la API ahora lista el campo.
  • Los ejemplos ya no mandan payer.email, y el Quickstart explica qué hace. Traían un correo de ejemplo, y una sesión creada así sólo la puede pagar ese buzón: el checkout no pregunta el correo, envía el código ahí y responde 403 PAYER_MISMATCH a cualquier otra cuenta. Una sesión con el correo equivocado no se corrige; se crea otra con una Idempotency-Key nueva.
  • 409 OBLIGATION_CONFLICT, explicado. Reutilizar un external_reference con otro monto, moneda, concepto o beneficiario responde 409 aunque la obligación no se haya pagado. Ahora el Quickstart y Sesiones de checkout dicen por qué y qué hacer si la cuota cambia antes de pagarse.
  • La Idempotency-Key se genera por intento en todos los ejemplos. Una llave fija copiada de esta documentación responde 409 IDEMPOTENCY_CONFLICT con otro cuerpo, o devuelve la sesión anterior, aunque haya vencido, con el mismo.
  • Cómo reconocer cada credencial y qué revisar ante un 401, en Autenticación y ambientes: la API key empieza con nmx_test_ o nmx_live_ y mide 52 caracteres; el webhook_secret (whsec_…) nunca va en Authorization.
  • Verificar la firma en PHP, con php://input y hash_equals.
  • Cómo pruebas dice que la primera vez el checkout te pide nombre, RFC y fecha de nacimiento antes de guardar la tarjeta, y que en pruebas puedes usar el RFC genérico del SAT, XAXX010101000. En beneficiary.rfc los RFC genéricos responden 422.
  • El webhook_secret rota de inmediato, sin período de gracia. El alta prometía que el secreto anterior y el nuevo convivían un tiempo; eso sólo vale para la API key.
  • Un WAF delante de tu webhook puede dejarte sin eventos. Un bloqueo o desafío responde 3xx o 4xx, y esas entregas no se reintentan. El alta explica cómo eximir la ruta en Cloudflare.
  • Para cambiar una cuota con una referencia nueva, espera a que venza la sesión anterior y confirma que ninguna sesión de esa referencia tiene un pago succeeded ni pending. Que el pagador ya no tenga la liga no basta: si paga las dos, son dos cobros.
  • La guía en PDF de /descargas/ se regeneró con estas correcciones. La anterior era del 15 de septiembre y todavía traía los ejemplos con payer.email y la llave fija.
  • Cuándo recibe el dinero el condominio, en Sesiones de checkout: qué confirma payment.succeeded y qué avisos existen hoy.

GET /health responde en api-beta.neatpagos.mx y api.neatpagos.mx, sin credencial, con 200 y un JSON corto. Antes ese host respondía una página 404 fuera de /v1. Sirve para comprobar que tu servidor llega al ambiente correcto; no es parte del contrato de v1 y su cuerpo puede cambiar sin aviso. Ningún endpoint de /v1 cambió.

2026-09-15 · correcciones a esta documentación

Sección titulada «2026-09-15 · correcciones a esta documentación»

Ningún cambio en la API: lo que cambió es lo que esta documentación decía de ella. Si integraste contra alguna de estas páginas, vale la pena releerlas.

  • payer.email no es un dato cosmético, es control de acceso. Si lo mandas, sólo una identidad con ese correo exacto puede abrir y pagar la sesión; cualquier otra recibe 403 PAYER_MISMATCH. Un correo mal escrito deja al pagador fuera de su propia deuda.
  • La liga de checkout no es de un solo uso, como decía la tabla de respuesta. Se puede abrir las veces que haga falta hasta expires_at o hasta que la sesión deje de estar open.
  • Una redirección en tu URL de webhook es un fallo definitivo. Neat no sigue 3xx, así que un http:// que redirige a https://, o una barra final de más o de menos, hace que no recibas ningún evento — y sin error visible de tu lado.
  • Un payment.pending no tiene continuación automática. No esperes un segundo evento que lo resuelva; consulta la sesión, y escríbenos si un cobro lleva horas ahí.
  • partially_refunded está reservado y v1 no lo emite: toda cancelación devuelve el cargo completo.
  • metadata es sólo de escritura —no vuelve en ninguna respuesta, webhook ni en el CSV— y al reutilizar un external_reference se conserva el de la primera sesión.
  • Reutilizar un external_reference no cierra la sesión anterior: su enlace sigue vivo hasta su propio vencimiento.
  • El archivo de conciliación no distingue una anulación en curso. Un pago con la cancelación solicitada se ve idéntico a uno limpio; para eso está cancellation_state en la API.
  • La especificación OpenAPI ahora dice que el mínimo y el máximo de amount_minor los fija tu comercio, y lleva el patrón de las claves de metadata.

El cuerpo de cada webhook trae dos campos nuevos dentro de resource: session_id, la sesión de checkout del pago, y external_reference, tu propia referencia de la obligación tal como la mandaste al crearla. Es un cambio aditivo: nada cambió de lugar ni de nombre, y si ya estabas procesando eventos no tienes que tocar nada.

Vale la pena saber que existen. Antes, para saber a qué cobro tuyo correspondía un payment.succeeded, había que guardar la relación entre tu referencia y el payment_id, o bajar el archivo de conciliación. Ahora el evento se basta solo.

La especificación OpenAPI (openapi.yaml) servía desde neat-mx-checkout-beta.web.app, que es el host del checkout y no el de la API. Ahora declara los dos hosts correctos, api-beta.neatpagos.mx para pruebas y api.neatpagos.mx para producción. Si generaste tu cliente a partir del archivo anterior, vuelve a generarlo o corrige la URL base; no cambió ningún endpoint ni ningún campo.

Publicación inicial de esta documentación para la API v1: alta de comercio, autenticación, creación y consulta de sesiones de checkout, redirección de regreso, estados, importes y comisiones, webhooks (eventos, firma, reintentos), archivo de conciliación, catálogo de errores y especificación OpenAPI.

El objeto payment, tanto en la sesión de checkout como en el cuerpo de cada webhook, incluye concept y payee_name.