Ir al contenido

Quickstart

Al terminar esta página habrás creado una sesión de checkout de prueba, redirigido a un pagador de prueba al checkout hospedado por Neat, y confirmado el resultado del cobro consultando la sesión.

Necesitas las credenciales de prueba que Neat te entrega al dar de alta tu comercio (ver Alta de tu comercio): una API key de pruebas y al menos un return_id registrado con la URL a la que Neat debe devolver al pagador. Guarda ambos valores como variables de entorno; nunca los escribas directamente en tu código.

Ventana de terminal
export NEAT_API_BASE="https://api-beta.neatpagos.mx/v1"
export NEAT_API_KEY="<tu API key de pruebas>"

La API key de pruebas empieza con nmx_test_ y mide 52 caracteres. El webhook_secret, que empieza con whsec_, no va en esta variable ni en ninguna llamada a la API: sólo sirve para verificar los webhooks. Si la variable llega vacía a tu código, la API responde 401 UNAUTHORIZED; ver Si recibes un 401.

NEAT_API_BASE es el ambiente de pruebas vigente. Neat te confirmará el dominio de producción al habilitar tu comercio para cobros en vivo, ver Autenticación y ambientes.

Envía el monto en centavos (amount_minor), tu propia referencia de la obligación (external_reference), la unidad que se cobra (unit_id, por ejemplo el departamento) y el return_id registrado. La cabecera Idempotency-Key es obligatoria: identifica esta solicitud de creación, no el cobro en sí, y te permite reintentar sin abrir dos sesiones si la respuesta original se perdió.

Genera una llave nueva para cada intento de cobro y guárdala junto a ese intento antes de llamar. Si la llamada se corta, repítela con la misma llave y el mismo cuerpo; si es un cobro nuevo, usa otra llave. Una llave fija sólo sirve una vez: con otro cuerpo responde 409 IDEMPOTENCY_CONFLICT, y con el mismo devuelve la sesión que ya creaste, aunque haya vencido.

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"
}'

En los ejemplos, la llave vive sólo mientras corre el código. En tu integración, guárdala con el intento de cobro antes de llamar, por ejemplo en la fila del intento en tu base de datos, y reutilízala con el mismo cuerpo si la llamada se corta: una llave generada de nuevo abre otra sesión.

Si tu comercio cobra en nombre de varios condominios, agrega beneficiary: quién recibe el dinero de este cobro. La clabe va siempre como texto, entre comillas. El detalle de cada campo está en Beneficiario por sesión.

Crear una sesión con beneficiario
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": "CONDO-00123-2026-09-402",
"concept": "Mensualidad de mantenimiento, septiembre 2026",
"amount_minor": 125000,
"currency": "MXN",
"return_id": "principal",
"unit_id": "402",
"beneficiary": {
"reference": "CONDO-00123",
"legal_name": "CONDOMINIO EJEMPLO LAS PALMAS AC",
"rfc": "CEP010101AB1",
"clabe": "032180000118359719"
}
}'

Respuesta (201 Created):

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"
}

checkout_url en este ejemplo usa un dominio de referencia: en el ambiente de pruebas real apunta al dominio de checkout que Neat te confirma al dar de alta tu comercio. La sesión expira 30 minutos después de creada; guarda session_id y tu external_reference para consultarla después.

Responde a la petición que originó el cobro (por ejemplo, el clic de tu usuario en “Pagar”) con una redirección HTTP a checkout_url. Neat captura el medio de pago; tu servidor no participa en esa parte del flujo.

Cuando el pagador termina, Neat lo redirige de vuelta a tu return_url, ver Redirección y regreso sobre por qué esa redirección no confirma el pago por sí sola. La fuente de verdad es el webhook (ver Webhooks: eventos y firma) o consultar la sesión directamente:

Consultar el estado de la sesión
curl "$NEAT_API_BASE/checkout-sessions/cs_164596add1a3" \
-H "Authorization: Bearer $NEAT_API_KEY"
200 OK — pago confirmado
{
"session_id": "cs_164596add1a3",
"status": "completed",
"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": {
"payment_id": "pay_3ac4efd9f068",
"version": 2,
"status": "succeeded",
"currency": "MXN",
"principal_amount_minor": 125000,
"payer_fee_minor": 3750,
"payer_fee_tax_minor": 600,
"provider_fee_minor": 0,
"provider_fee_tax_minor": 0,
"charged_amount_minor": 129350,
"provider_net_amount_minor": 125000,
"refunded_amount_minor": 0,
"fee_bearer": "payer",
"cancellation_state": "none",
"paid_at": "2026-09-14T23:17:17.894Z",
"category": "maintenance_fee",
"concept": "Mensualidad de mantenimiento, septiembre 2026",
"payee_name": "Administradora Ejemplo, S.A. de C.V."
}
}

payee_name es el nombre de tu comercio tal como quedó registrado en el alta o, si la sesión trae beneficiary, su legal_name.

El ejemplo no manda category porque el comercio tiene habilitada una sola, la cuota de mantenimiento, y la respuesta la devuelve igual. Si tu comercio cobra varias (por ejemplo, renta y póliza de renta), mándala en cada sesión; ver Categoría del cobro.