Ir al contenido

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.

POST /v1/checkout-sessions
Crear una sesión de checkout
IDEMPOTENCY_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" }
}'

<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.

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.

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.

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.

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.

Datos de ejemplo, ficticios
"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_reference con otro beneficiary responde 409 OBLIGATION_CONFLICT. Por eso el external_reference tiene que ser único entre todos tus condominios, por ejemplo CONDO-00123-2026-09-402. Si te equivocaste en la CLABE antes del primer pago, escríbenos con el external_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í responde 422 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, el beneficiary.reference y el unit_id. Si tu comercio no nombra beneficiario, por tu comercio y el unit_id.
  • Se compara exacto. "301", "Depto 301" y "301 " no son la misma unidad (el último además se rechaza con 422 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_reference con otro unit_id responde 409 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.

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.succeeded confirma 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, no amount_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_reference del 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.

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.

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:

  1. Que haya pasado el expires_at de 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.
  2. Que ninguna de sus sesiones tenga un pago succeeded ni pending. Consulta con GET /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 recibe 409 PAYMENT_IN_PROGRESS o 409 CHECKOUT_NOT_PAYABLE—, pero si le mandaste las dos al pagador, va a ver una fallar.
  • El metadata de la sesión nueva no reemplaza al de la obligación. El de la primera es el que queda. Como además metadata no vuelve en ninguna respuesta, no hay forma de consultarlo: si el dato tiene que viajar, mándalo en external_reference o guárdalo de tu lado contra el session_id.

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.

201 Created
{
"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.
GET /v1/checkout-sessions/{sessionId}
Consultar una sesión
curl "$NEAT_API_BASE/checkout-sessions/cs_164596add1a3" \
-H "Authorization: Bearer $NEAT_API_KEY"
200 OK — antes de cualquier intento de pago
{
"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.

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.