Sesiones de checkout
Al terminar esta página sabrás qué campos acepta la creación de una sesión, cómo se identifica cada obligación de cobro, y cómo consultar su estado después de crearla.
Crear una sesión
Sección titulada «Crear una sesión»POST /v1/checkout-sessionsIDEMPOTENCY_KEY="checkout-$(uuidgen)"
curl -X POST "$NEAT_API_BASE/checkout-sessions" \ -H "Authorization: Bearer $NEAT_API_KEY" \ -H "Idempotency-Key: $IDEMPOTENCY_KEY" \ -H "Content-Type: application/json" \ -d '{ "external_reference": "CUOTA-2026-09-000123", "concept": "Mensualidad de mantenimiento, septiembre 2026", "amount_minor": 125000, "currency": "MXN", "return_id": "principal", "unit_id": "301", "payer": { "email": "<correo de tu equipo de pruebas>", "name": "Ana Torres" }, "metadata": { "order_id": "ORD-000123" } }'import { randomUUID } from 'node:crypto';
const idempotencyKey = `checkout-${randomUUID()}`;
const response = await fetch(`${process.env.NEAT_API_BASE}/checkout-sessions`, { method: 'POST', headers: { Authorization: `Bearer ${process.env.NEAT_API_KEY}`, 'Idempotency-Key': idempotencyKey, 'Content-Type': 'application/json', }, body: JSON.stringify({ external_reference: 'CUOTA-2026-09-000123', concept: 'Mensualidad de mantenimiento, septiembre 2026', amount_minor: 125000, currency: 'MXN', return_id: 'principal', unit_id: '301', payer: { email: '<correo de tu equipo de pruebas>', name: 'Ana Torres' }, metadata: { order_id: 'ORD-000123' }, }),});
const session = await response.json();<correo de tu equipo de pruebas> es un marcador: la API lo rechaza con 422 VALIDATION_ERROR si
lo mandas tal cual. Pon ahí el correo de quien va a pagar, o quita el campo: con payer.email, sólo
esa dirección puede pagar la sesión (ver el aviso debajo de la tabla). Genera una Idempotency-Key nueva por cada intento de cobro, ver
Idempotency-Key.
Cuerpo de la petición
Sección titulada «Cuerpo de la petición»La API rechaza cualquier propiedad fuera de esta lista con 422 VALIDATION_ERROR.
| Campo | Obligatorio | Tipo y validación |
|---|---|---|
external_reference |
Sí | Texto ASCII de 1 a 100 caracteres: letras, números, ., _, -. Identifica tu obligación de cobro; ver más abajo. |
category |
Según tu comercio | maintenance_fee, rent o rent_guarantee_insurance: qué está pagando el pagador. Opcional si tu comercio tiene habilitada una sola categoría. Ver Categoría del cobro. |
concept |
Sí | Texto de 1 a 140 caracteres. Sin caracteres de control ni </>. Se muestra al pagador. |
amount_minor |
Sí | Entero positivo en centavos: MXN 12,850.00 es 1285000, y 12850 es MXN 128.50. Entre el mínimo y el máximo de tu comercio (ver nota abajo). |
currency |
Sí | Literal "MXN". Cualquier otro valor devuelve 422 VALIDATION_ERROR. |
return_id |
Sí | Texto ASCII de 1 a 50 caracteres: letras, números, _, -. Debe estar registrado y activo (ver Alta de tu comercio). |
unit_id |
Sí | Texto de 1 a 64 caracteres: letras, números, espacios y ., _, #, /, -; empieza con letra o número y no termina en espacio. La unidad (departamento, lote) que se cobra. Ver Unidad. |
payer |
No | Objeto con email y/o name. No puede ir vacío ni traer otras propiedades. |
payer.email |
No | Correo válido de hasta 254 caracteres, guardado en minúsculas. No es cosmético: fija quién puede pagar. Ver el aviso debajo de la tabla. |
payer.name |
No | Texto de 1 a 100 caracteres, sin caracteres de control ni HTML. |
metadata |
No | Objeto de hasta 10 pares. Claves de 1 a 40 caracteres [A-Za-z0-9_-]; valores de texto de hasta 200 caracteres, sin caracteres de control. Sólo de escritura: no vuelve en ninguna respuesta, webhook ni en el CSV. |
beneficiary |
Según tu comercio | Solo si cobras por varios beneficiarios: quién recibe el dinero de este cobro. Obligatorio en ese caso y rechazado en cualquier otro. Ver Beneficiario por sesión. |
fee_bearer |
Según tu comercio | payer o provider: quién paga la comisión de Neat. Opcional si tu comercio tiene habilitada una sola forma. Ver Quién paga la comisión. |
Además, el cuerpo completo no puede superar 16 KiB.
Categoría del cobro
Sección titulada «Categoría del cobro»category dice qué está pagando el pagador, y con ella cambian el texto del checkout y de los correos
que le mandamos:
| Valor | El pagador ve |
|---|---|
maintenance_fee |
Cuota de mantenimiento |
rent |
Renta |
rent_guarantee_insurance |
Póliza de renta |
Neat habilita las categorías de cada comercio en el alta. Si tu comercio tiene una sola, puedes omitir
category y se usa esa; un comercio dado de alta antes de que existiera el campo cobra cuotas de
mantenimiento y no tiene que cambiar nada. Si tiene varias, category es obligatoria y sin ella la API
responde 422 VALIDATION_ERROR con field: "category". Una categoría que tu comercio no tiene
habilitada responde 422 CATEGORY_NOT_ALLOWED.
La categoría es un término de la obligación, como el monto: vuelve en la sesión, en el pago, en el
webhook y en el archivo de conciliación, y reusar un
external_reference con otra categoría responde 409 OBLIGATION_CONFLICT.
Quién paga la comisión
Sección titulada «Quién paga la comisión»fee_bearer dice quién paga la comisión de Neat en esta sesión:
| Valor | El pagador paga | El depósito |
|---|---|---|
payer |
amount_minor más la comisión y su IVA |
amount_minor completo |
provider |
Exactamente amount_minor; el checkout no muestra comisión |
amount_minor menos la comisión y su IVA |
Neat habilita las formas de cada comercio. Si tu comercio tiene una sola, puedes omitir fee_bearer
y se usa esa. Un comercio dado de alta antes de que existiera el campo cobra la comisión al pagador y
no tiene que cambiar nada. Si Neat después cambia esa forma única a que tu comercio la absorba, tus
sesiones nuevas sin fee_bearer la absorben sin cambios; si mandabas fee_bearer: "payer", empiezan a
responder 422 FEE_BEARER_NOT_ALLOWED. Si tiene las dos, fee_bearer es obligatorio y sin él la
API responde 422 VALIDATION_ERROR con field: "fee_bearer". Una forma que tu comercio no tiene
habilitada responde 422 FEE_BEARER_NOT_ALLOWED.
Queda fijo en la sesión al crearla: lo que el pagador ve en el checkout es lo que se le cobra, aunque Neat cambie quién paga la comisión en tu comercio mientras la sesión está abierta. Vuelve en la respuesta de creación, en la sesión, en el pago, en el webhook y en el archivo de conciliación. Los montos y el cálculo están en Importes y comisiones.
Con provider, el monto tiene que dejar algo que depositar con cualquier tarjeta; si no lo deja, la API
responde 422 AMOUNT_BELOW_FEE con field: "amount_minor". Con las tasas de tarjeta esto solo pasa con
montos de unos pocos centavos, muy por debajo del mínimo.
Beneficiario por sesión
Sección titulada «Beneficiario por sesión»Si tu sistema cobra en nombre de varios condominios o administradoras, cada sesión dice a quién le
pagamos. Neat deposita directo en la cuenta del beneficiario; tu comercio no recibe ni reparte el
dinero. Este modo lo habilita Neat para tu comercio: sin él, beneficiary responde
422 BENEFICIARY_NOT_ALLOWED; con él, una sesión sin beneficiary responde
422 BENEFICIARY_REQUIRED.
"beneficiary": { "reference": "CONDO-00123", "legal_name": "CONDOMINIO EJEMPLO LAS PALMAS AC", "rfc": "CEP010101AB1", "clabe": "032180000118359719"}Estos datos son ficticios: no los mandes tal cual, ni en pruebas. Usa los del condominio de cada cobro. El Quickstart tiene la llamada completa en cURL, Node y PHP.
| Campo | Validación |
|---|---|
reference |
Tu identificador del beneficiario, de 1 a 64 caracteres [A-Za-z0-9._-]. Usa siempre el mismo para el mismo condominio. |
legal_name |
Razón social del titular de la cuenta, de 1 a 120 caracteres, sin caracteres de control, invisibles ni HTML. Es el nombre que ve el pagador. |
rfc |
RFC del titular: 12 caracteres para persona moral, 13 para persona física. Se guarda en mayúsculas. Los RFC genéricos del SAT (XAXX010101000, XEXX010101000) responden 422. |
clabe |
18 dígitos como texto, con su dígito verificador válido. Si la lees de una columna numérica, conviértela a texto antes de serializar: en PHP, json_encode de un entero pierde los ceros iniciales (002, 012, 014) y la API responde 422. |
Cómo lo trata Neat:
- La cuenta es un término de la obligación, igual que el monto: reutilizar un
external_referencecon otrobeneficiaryresponde409 OBLIGATION_CONFLICT. Por eso elexternal_referencetiene que ser único entre todos tus condominios, por ejemploCONDO-00123-2026-09-402. Si te equivocaste en la CLABE antes del primer pago, escríbenos con elexternal_reference; no la corrijas cambiando la referencia. - Neat deposita a la CLABE que declara la sesión, a nombre del titular que declara. Revisa que la CLABE, el RFC y la razón social correspondan al condominio antes de mandarlos: el depósito sigue esos datos.
- La CLABE no vuelve en ninguna respuesta, webhook, correo ni archivo de conciliación. Tampoco la
pongas en
metadata: en este modo, un valor con forma de CLABE ahí responde422 VALIDATION_ERROR. - En la página de pago y en la confirmación, el pagador ve «Le pagas a», seguido de
legal_name, y «vía», seguido del nombre de tu comercio. Si los dos nombres coinciden, «vía» no aparece.
unit_id es tu identificador del departamento, lote o local que se cobra: "301", "Torre B PG-1",
"Lote 14/2". Es obligatorio en cada sesión. Neat agrupa bajo una misma unidad todos los cobros que la
nombran y recuerda quién fue el último pagador que entró al checkout de esa unidad.
- Única dentro del beneficiario. Si cobras por varios condominios, el
"301"de uno y el"301"de otro son unidades distintas: la unidad se identifica por tu comercio, elbeneficiary.referencey elunit_id. Si tu comercio no nombra beneficiario, por tu comercio y elunit_id. - Se compara exacto.
"301","Depto 301"y"301 "no son la misma unidad (el último además se rechaza con422 VALIDATION_ERROR). Manda siempre el mismo valor para la misma unidad, mes a mes. - Es un término inmutable de la obligación, como el monto. Reutilizar un
external_referencecon otrounit_idresponde409 OBLIGATION_CONFLICT. - Se crea cuando el pagador entra al checkout, no al crear la sesión: una sesión que nadie abre no deja unidad registrada.
Cuándo recibe el dinero el condominio
Sección titulada «Cuándo recibe el dinero el condominio»Después de confirmar el cobro, Neat transfiere por SPEI a la CLABE que declaró la sesión, a nombre de
su legal_name. Lo que conviene saber hoy:
payment.succeededconfirma el cobro, no el depósito. La transferencia al condominio es un paso posterior.- Quien paga se entera por correo: recibe uno al confirmarse el cobro y otro cuando la transferencia se hace o si falla.
- Si tu comercio absorbe la comisión, el depósito llega neto: el monto es
provider_net_amount_minor, noamount_minor. Avísale al condominio. - Tu comercio no recibe aviso de la transferencia. No hay un evento de webhook para ella, y el
archivo de conciliación no trae su estado. Si un condominio pregunta
por un depósito, escríbenos con el
external_referencedel cobro.
Esta documentación no fija un plazo de depósito. Si necesitas uno para informar a tus condominios, pregúntale a tu contacto en Neat.
external_reference: identifica tu obligación, no tu intento de cobro
Sección titulada «external_reference: identifica tu obligación, no tu intento de cobro»Neat usa external_reference para reconocer la misma obligación de cobro entre distintas llamadas de
tu comercio. Reutilizarlo se comporta así:
| Situación | Resultado |
|---|---|
| Referencia nueva | Crea una obligación y una sesión nuevas. |
Misma referencia, mismos amount_minor, currency, category, concept y beneficiary, sin pago exitoso ni en curso |
Abre otra sesión sobre la misma obligación (por ejemplo, para reintentar tras un enlace vencido). La sesión anterior sigue viva con su propio enlace; ver debajo. |
Misma referencia con amount_minor, currency, category, concept, beneficiary o unit_id distintos |
409 OBLIGATION_CONFLICT, aunque la obligación no se haya pagado. |
| Misma referencia y mismos términos, obligación ya pagada | 409 OBLIGATION_ALREADY_PAID |
| Misma referencia y mismos términos, cobro en curso | 409 PAYMENT_IN_PROGRESS |
Si el cliente paga cada mes, usa una referencia que distinga el período: CUOTA-2026-09-000123 y
CUOTA-2026-10-000123 son obligaciones distintas. payer, metadata y fee_bearer no son términos:
cambiarlos no provoca el 409. fee_bearer queda fijo en cada sesión, así que dos ligas vivas de la
misma referencia creadas con distinto fee_bearer le muestran al pagador totales distintos.
Por qué los términos no cambian
Sección titulada «Por qué los términos no cambian»La primera sesión fija los términos de la obligación, y un concept con otro texto ya cuenta como
distinto. Es a propósito:
- Todas las ligas de una referencia cobran la misma obligación. Solo la comisión puede variar entre
ligas creadas con distinto
fee_bearer. La sesión anterior sigue viva y puede estar en manos del pagador; si una llamada nueva pudiera cambiar el monto, esa liga cobraría algo que el pagador no vio. - Una obligación no se reapunta a otra cuenta. Si cobras por beneficiario, la CLABE es un término: una segunda llamada no puede desviar a otra cuenta el dinero de una deuda ya emitida.
- Tu conciliación se cruza por esta referencia. Los webhooks y el archivo CSV la traen: una referencia, un monto, un beneficiario.
Si la cuota cambia antes de pagarse
Sección titulada «Si la cuota cambia antes de pagarse»Un recargo por mora o una corrección de monto o de concepto es otra obligación para la API. Usa una
referencia nueva con una versión, por ejemplo CUOTA-2026-09-000123-R1, pero sólo después de dos
comprobaciones sobre la referencia anterior:
- Que haya pasado el
expires_atde su sesión más reciente. Hasta entonces la liga puede iniciar un pago, y una sesión no se puede cerrar antes. Que el pagador ya no tenga la liga no basta: puede haberla guardado o recuperarla del correo. - Que ninguna de sus sesiones tenga un pago
succeedednipending. Consulta conGET /v1/checkout-sessions/{sessionId}cada sesión que creaste para esa referencia, no sólo la última: cada una devuelve su propio pago, y un pago iniciado en una sesión anterior, o justo antes del vencimiento, puede seguir en curso.
Si emites la referencia nueva antes, el pagador puede terminar pagando las dos, y serían dos cobros.
Si lo que está mal es la CLABE y todavía no hay pago, escríbenos con el external_reference; no la
corrijas con una referencia nueva.
Dos cosas que conviene saber al reutilizar una referencia:
- La sesión anterior no se cierra. Su enlace sigue funcionando hasta su propio
expires_at, así que por un rato existen dos ligas vivas para la misma obligación. Sólo una puede terminar en cobro —la primera que reserve el pago gana y la otra recibe409 PAYMENT_IN_PROGRESSo409 CHECKOUT_NOT_PAYABLE—, pero si le mandaste las dos al pagador, va a ver una fallar. - El
metadatade la sesión nueva no reemplaza al de la obligación. El de la primera es el que queda. Como ademásmetadatano vuelve en ninguna respuesta, no hay forma de consultarlo: si el dato tiene que viajar, mándalo enexternal_referenceo guárdalo de tu lado contra elsession_id.
Idempotency-Key
Sección titulada «Idempotency-Key»Obligatoria en cada creación. Genera una nueva por cada intento de cobro, guárdala junto a ese
intento y repítela sólo si reintentas esa misma llamada con el mismo cuerpo. Lleva de 8 a 128
caracteres ASCII: letras, números, ., _, : y -. Una llave fuera de ese largo o con otro
carácter responde 422 VALIDATION_ERROR con "field": "Idempotency-Key". Ver el detalle completo,
incluyendo qué pasa con solicitudes repetidas, en
Reintentos e idempotencia.
Respuesta
Sección titulada «Respuesta»{ "session_id": "cs_164596add1a3", "checkout_url": "https://pago.neat.example/pagar/cs_164596add1a3.CQGg0fEWT5o…", "expires_at": "2026-09-14T23:45:55.013Z", "status": "open", "fee_bearer": "payer"}| Campo | Descripción |
|---|---|
session_id |
Identificador de la sesión. Único en tu comercio. |
checkout_url |
Página hospedada por Neat a la que debes redirigir al pagador. Termina en /pagar/<token>; el token es opaco y se puede abrir las veces que haga falta hasta expires_at o hasta que la sesión deje de estar open. |
expires_at |
Vencimiento del enlace: 30 minutos después de creado, fijo. |
status |
Siempre "open" en la respuesta de creación. |
fee_bearer |
Quién paga la comisión en esta sesión: el que mandaste, o el que Neat habilitó para tu comercio si no mandaste ninguno. |
Consultar una sesión
Sección titulada «Consultar una sesión»GET /v1/checkout-sessions/{sessionId}curl "$NEAT_API_BASE/checkout-sessions/cs_164596add1a3" \-H "Authorization: Bearer $NEAT_API_KEY"const response = await fetch(`${process.env.NEAT_API_BASE}/checkout-sessions/cs_164596add1a3`,{ headers: { Authorization: `Bearer ${process.env.NEAT_API_KEY}` } });
const session = await response.json();{ "session_id": "cs_164596add1a3", "status": "open", "external_reference": "CUOTA-2026-09-000123", "category": "maintenance_fee", "concept": "Mensualidad de mantenimiento, septiembre 2026", "amount_minor": 125000, "currency": "MXN", "fee_bearer": "payer", "expires_at": "2026-09-14T23:45:55.013Z", "payment": null}payment es null hasta el primer intento de cobro. Después de un intento, muestra el pago más
reciente de la sesión, ver la forma completa de payment en
Importes y comisiones. Un sessionId que no existe, o que pertenece
a otro comercio, devuelve 404 RESOURCE_NOT_FOUND en ambos casos; la API nunca revela si el identificador
existe bajo otra credencial.
Errores de esta sección
Sección titulada «Errores de esta sección»| HTTP | Código | Cuándo |
|---|---|---|
401 |
UNAUTHORIZED / INVALID_API_KEY |
Ver Autenticación y ambientes. |
403 |
PROVIDER_DISABLED |
Tu comercio está deshabilitado. |
404 |
RESOURCE_NOT_FOUND |
La sesión no existe o pertenece a otro comercio. |
409 |
IDEMPOTENCY_CONFLICT |
Repetiste Idempotency-Key con un cuerpo distinto. |
409 |
OBLIGATION_CONFLICT / OBLIGATION_ALREADY_PAID / PAYMENT_IN_PROGRESS |
Ver la tabla de external_reference arriba. |
422 |
VALIDATION_ERROR |
Un campo no cumple su formato, o el monto está fuera de tus límites. |
422 |
RETURN_NOT_REGISTERED |
El return_id no está registrado o no está activo. |
422 |
BENEFICIARY_REQUIRED / BENEFICIARY_NOT_ALLOWED |
Ver Beneficiario por sesión. |
422 |
CATEGORY_NOT_ALLOWED |
Ver Categoría del cobro. |
422 |
FEE_BEARER_NOT_ALLOWED / AMOUNT_BELOW_FEE |
Ver Quién paga la comisión. |
429 |
RATE_LIMITED |
Excediste el límite por minuto de este endpoint. |
Catálogo completo en Errores.