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(payeroprovider) en la respuesta de creación, en la sesión (GET /v1/checkout-sessions/{sessionId}), en el pago y en eldatade cada webhook. Conprovider,provider_fee_minoryprovider_fee_tax_minordejan de ser0,payer_fee_minorypayer_fee_tax_minorquedan en0, yprovider_net_amount_minores el monto menos la comisión y su IVA. Los pagos anteriores traenpayeren la API, el webhook y el CSV. - Columna nueva en el archivo de conciliación:
fee_bearer, al final, después decategory. 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 es422 VALIDATION_ERRORconfield: "fee_bearer". - Errores nuevos:
422 FEE_BEARER_NOT_ALLOWEDsi mandas una forma que tu comercio no tiene habilitada, y422 AMOUNT_BELOW_FEEsi 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_referencecon otrofee_bearerno responde409.
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:
categoryen la sesión (GET /v1/checkout-sessions/{sessionId}), en el pago y en eldatade cada webhook. En el pago puede sernullsolo 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_ALLOWEDsi mandas una categoría que tu comercio no tiene habilitada. Si tu comercio tiene varias y no mandascategory, la respuesta es422 VALIDATION_ERRORconfield: "category". - Término de la obligación: reusar un
external_referencecon otra categoría responde409 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-Keyausente 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
beneficiaryo responde422 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 responde403 PAYER_MISMATCHa cualquier otra cuenta. Una sesión con el correo equivocado no se corrige; se crea otra con unaIdempotency-Keynueva. 409 OBLIGATION_CONFLICT, explicado. Reutilizar unexternal_referencecon otro monto, moneda, concepto o beneficiario responde409aunque 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-Keyse genera por intento en todos los ejemplos. Una llave fija copiada de esta documentación responde409 IDEMPOTENCY_CONFLICTcon 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 connmx_test_onmx_live_y mide 52 caracteres; elwebhook_secret(whsec_…) nunca va enAuthorization. - Verificar la firma en PHP, con
php://inputyhash_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. Enbeneficiary.rfclos RFC genéricos responden422. - El
webhook_secretrota 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
3xxo4xx, 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
succeedednipending. 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 conpayer.emaily la llave fija. - Cuándo recibe el dinero el condominio, en
Sesiones de checkout: qué
confirma
payment.succeededy qué avisos existen hoy.
2026-09-16
Sección titulada «2026-09-16»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.emailno 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 recibe403 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_ato hasta que la sesión deje de estaropen. - Una redirección en tu URL de webhook es un fallo definitivo. Neat no sigue
3xx, así que unhttp://que redirige ahttps://, 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.pendingno 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_refundedestá reservado yv1no lo emite: toda cancelación devuelve el cargo completo.metadataes sólo de escritura —no vuelve en ninguna respuesta, webhook ni en el CSV— y al reutilizar unexternal_referencese conserva el de la primera sesión.- Reutilizar un
external_referenceno 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_stateen la API. - La especificación OpenAPI ahora dice que el mínimo y el máximo de
amount_minorlos fija tu comercio, y lleva el patrón de las claves demetadata.
2026-09-15
Sección titulada «2026-09-15»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.
2026-09-14
Sección titulada «2026-09-14»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.