Referencia de API
Referencia compacta de los tres endpoints de comercio de la API de Neat México v1. Para el flujo
completo con contexto, ve a Sesiones de checkout,
Redirección y regreso y Archivo CSV.
Todos los endpoints:
- Requieren
Authorization: Bearer <tu API key>. - Devuelven
Cache-Control: no-store. - Devuelven errores con la forma
{ "error": { "code", "message", "field"?, "request_id" } }, ver Errores.
| Método y ruta | Límite | Descripción |
|---|---|---|
POST /v1/checkout-sessions |
120/min | Crea una sesión de checkout. |
GET /v1/checkout-sessions/{sessionId} |
300/min | Consulta el estado de una sesión y su pago más reciente. |
GET /v1/reconciliation/payments.csv |
10/min | Descarga el CSV con todos los pagos de tu comercio. |
POST /v1/checkout-sessions
Sección titulada «POST /v1/checkout-sessions»Crea una obligación de cobro y una sesión de checkout para ella.
Cabeceras: Authorization (obligatoria), Idempotency-Key (obligatoria, 8–128 caracteres
[A-Za-z0-9._:-], una nueva por cada intento de cobro), Content-Type: application/json.
Cuerpo:
| Campo | Tipo | Obligatorio |
|---|---|---|
external_reference |
string, 1–100 ASCII [A-Za-z0-9._-] |
Sí |
concept |
string, 1–140 caracteres | Sí |
amount_minor |
integer positivo, centavos | Sí |
currency |
"MXN" |
Sí |
return_id |
string, 1–50 ASCII [A-Za-z0-9_-] |
Sí |
unit_id |
string, 1–64: letras, números, espacios, ._#/- |
Sí |
payer.email |
string, correo, ≤254 | No |
payer.name |
string, 1–100 | No |
metadata |
objeto, hasta 10 pares string:string | No |
beneficiary |
objeto reference, legal_name, rfc, clabe (string de 18 dígitos) |
Según tu comercio |
fee_bearer |
"payer" o "provider" |
Según tu comercio |
payer.email decide quién puede pagar: si lo mandas, sólo esa dirección recibe el código y puede
pagar la sesión. Reutilizar un external_reference con otro monto, moneda, concepto, beneficiario o unit_id
responde 409 OBLIGATION_CONFLICT aunque no se haya pagado. Ver
Sesiones 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" }'import { randomUUID } from 'node:crypto';
await fetch(`${process.env.NEAT_API_BASE}/checkout-sessions`, { method: 'POST', headers: { Authorization: `Bearer ${process.env.NEAT_API_KEY}`, 'Idempotency-Key': `checkout-${randomUUID()}`, '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', }),});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"}Detalle completo de campos, reglas de external_reference, beneficiary y errores en
Sesiones de checkout.
GET /v1/checkout-sessions/{sessionId}
Sección titulada «GET /v1/checkout-sessions/{sessionId}»Consulta una sesión y su pago más reciente.
curl "$NEAT_API_BASE/checkout-sessions/cs_164596add1a3" \ -H "Authorization: Bearer $NEAT_API_KEY"await fetch(`${process.env.NEAT_API_BASE}/checkout-sessions/cs_164596add1a3`, {headers: { Authorization: `Bearer ${process.env.NEAT_API_KEY}` },});Respuesta 200 OK:
{ "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." }}payment es null antes del primer intento. Ver el significado de cada campo en
Importes y comisiones y cada estado en
Estados y glosario.
GET /v1/reconciliation/payments.csv
Sección titulada «GET /v1/reconciliation/payments.csv»Descarga el CSV con todos los pagos de tu comercio, sin filtro de fecha.
curl "$NEAT_API_BASE/reconciliation/payments.csv" \ -H "Authorization: Bearer $NEAT_API_KEY" \ -o payments.csvconst response = await fetch(`${process.env.NEAT_API_BASE}/reconciliation/payments.csv`, {headers: { Authorization: `Bearer ${process.env.NEAT_API_KEY}` },});const csv = await response.text();Respuesta 200 OK: Content-Type: text/csv; charset=utf-8. Columnas y ejemplo completo en
Archivo CSV.
Especificación descargable
Sección titulada «Especificación descargable»La forma exacta de cada request y respuesta también está disponible como OpenAPI 3.1, ver OpenAPI.