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.
Antes de empezar
Sección titulada «Antes de empezar»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.
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.
1. Crear una sesión de checkout
Sección titulada «1. Crear una sesión de checkout»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.
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" }'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', }),});
const session = await response.json();<?php$apiBase = getenv('NEAT_API_BASE');$apiKey = getenv('NEAT_API_KEY');if (!$apiBase || !$apiKey) { throw new RuntimeException('Faltan NEAT_API_BASE o NEAT_API_KEY.');}
$idempotencyKey = 'checkout-' . bin2hex(random_bytes(16));
$body = [ 'external_reference' => 'CUOTA-2026-09-000123', 'concept' => 'Mensualidad de mantenimiento, septiembre 2026', 'amount_minor' => 125000, 'currency' => 'MXN', 'return_id' => 'principal', 'unit_id' => '301',];
$curl = curl_init($apiBase . '/checkout-sessions');curl_setopt_array($curl, [ CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . $apiKey, 'Idempotency-Key: ' . $idempotencyKey, 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode($body, JSON_THROW_ON_ERROR), CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 15,]);$responseBody = curl_exec($curl);if ($responseBody === false) { throw new RuntimeException('Sin respuesta de Neat: reintenta con la misma Idempotency-Key, ' . $idempotencyKey);}
$session = json_decode($responseBody, true, 512, JSON_THROW_ON_ERROR);$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);if ($status !== 201) { throw new RuntimeException('Neat respondió ' . $status . ': ' . ($session['error']['code'] ?? 'sin código'));}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 cobras por varios beneficiarios
Sección titulada «Si cobras por varios beneficiarios»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.
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" } }'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: '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', }, }),});
const session = await response.json();<?php$apiBase = getenv('NEAT_API_BASE');$apiKey = getenv('NEAT_API_KEY');if (!$apiBase || !$apiKey) { throw new RuntimeException('Faltan NEAT_API_BASE o NEAT_API_KEY.');}
$idempotencyKey = 'checkout-' . bin2hex(random_bytes(16));
$body = [ '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', ],];
$curl = curl_init($apiBase . '/checkout-sessions');curl_setopt_array($curl, [ CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . $apiKey, 'Idempotency-Key: ' . $idempotencyKey, 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode($body, JSON_THROW_ON_ERROR), CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 15,]);$responseBody = curl_exec($curl);if ($responseBody === false) { throw new RuntimeException('Sin respuesta de Neat: reintenta con la misma Idempotency-Key, ' . $idempotencyKey);}
$session = json_decode($responseBody, true, 512, JSON_THROW_ON_ERROR);$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);if ($status !== 201) { throw new RuntimeException('Neat respondió ' . $status . ': ' . ($session['error']['code'] ?? 'sin código'));}Respuesta (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.
2. Redirigir al pagador
Sección titulada «2. Redirigir al pagador»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.
3. Confirmar el resultado
Sección titulada «3. Confirmar el resultado»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:
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": "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.
Siguientes pasos
Sección titulada «Siguientes pasos»- Sesiones de checkout: todos los campos, límites y errores de creación.
- Importes y comisiones: quién paga la comisión y cómo se calcula.
- Webhooks: eventos y firma: cómo recibir el resultado sin tener que hacer polling.