Autenticación y ambientes
Al terminar esta página sabrás qué encabezado enviar en cada request, qué significa cada error de autenticación y qué distingue al ambiente de pruebas del de producción.
Encabezado de autorización
Sección titulada «Encabezado de autorización»Cada request a un endpoint de comercio lleva tu API key como token portador:
Authorization: Bearer <tu API key>No hay otro mecanismo de autenticación para el servidor de tu comercio: sin este encabezado, con un
formato distinto a Bearer <token> o con el token vacío, la API responde 401 UNAUTHORIZED antes de
intentar validar la llave.
| Situación | HTTP | Código |
|---|---|---|
Sin encabezado Authorization, sin el prefijo Bearer o con el token vacío |
401 |
UNAUTHORIZED |
| API key inexistente o revocada | 401 |
INVALID_API_KEY |
| API key válida pero comercio deshabilitado | 403 |
PROVIDER_DISABLED |
Un 401 INVALID_API_KEY no distingue entre una llave inexistente y una revocada. Ambos casos piden lo
mismo de tu parte, confirmar la credencial vigente con Neat, así que la API no expone esa diferencia.
Cómo reconocer cada credencial
Sección titulada «Cómo reconocer cada credencial»Neat te entrega dos credenciales distintas, y sólo una va en las llamadas a la API:
| Credencial | Empieza con | Largo | Dónde va |
|---|---|---|---|
| API key de pruebas | nmx_test_ |
52 caracteres | Authorization: Bearer <API key> contra https://api-beta.neatpagos.mx. |
| API key de producción | nmx_live_ |
52 caracteres | Authorization: Bearer <API key> contra https://api.neatpagos.mx. |
webhook_secret |
whsec_ |
49 caracteres | Sólo en tu servidor, para verificar la firma de cada webhook. Nunca en Authorization. |
Si tu código lee la llave de una variable de entorno o de un secret manager, comprueba que llegue
completa antes de llamar: que empiece con nmx_ y mida 52 caracteres, sin espacios ni saltos de línea
alrededor.
Si recibes un 401
Sección titulada «Si recibes un 401»| Código | Qué revisar |
|---|---|
UNAUTHORIZED |
La API no encontró un token. Lo típico es la variable de la llave vacía o sin definir, que deja el encabezado en Bearer a secas. También pasa si falta el encabezado o si el prefijo no es exactamente Bearer (con B mayúscula y un espacio): bearer en minúscula no sirve. |
INVALID_API_KEY |
Hay un token, pero no es una API key vigente de este ambiente. Las causas más comunes: mandaste el webhook_secret (whsec_…) en vez de la API key, la llave se cortó al copiarla, usas la llave de producción contra pruebas o al revés, la llave fue revocada, o en JavaScript la variable no está definida y el encabezado sale como Bearer undefined. |
Cuando pidas ayuda, comparte el request_id de la respuesta, nunca la llave.
Qué identifica la API key
Sección titulada «Qué identifica la API key»La API key identifica exclusivamente a tu comercio y a su ambiente (pruebas o producción). No hay un campo en el cuerpo de la petición para elegir otro comercio, otra cuenta de destino o otro ambiente: eso siempre sale de la credencial, nunca de la request.
Ambientes
Sección titulada «Ambientes»Pruebas y producción son credenciales y despliegues separados, no un valor que se declare en la request. No existe un encabezado ni un parámetro de ambiente.
| Ambiente | URL de API |
|---|---|
| Pruebas | https://api-beta.neatpagos.mx |
| Producción | https://api.neatpagos.mx |
Las rutas van bajo /v1, así que una sesión de checkout de pruebas se crea con
POST https://api-beta.neatpagos.mx/v1/checkout-sessions.
Fuera de /v1, la API responde a una sola ruta: GET /health, sin credencial, con 200 y un JSON
corto. Sirve para comprobar desde tu servidor que llegas al ambiente correcto. No es parte del contrato
de v1: no lleva datos de tu comercio, su cuerpo puede cambiar sin aviso y no lo uses para decidir si
crear una sesión o no.
Los dos dominios atienden solo llamadas de servidor a servidor. La página que abre quien paga vive en
otro dominio, el que viene en checkout_url al crear la sesión: no la armes tú a mano, porque ese
dominio puede cambiar y el de la API no.
Usa siempre tu API key de pruebas contra el ambiente de pruebas. Una API key de producción contra el
ambiente de pruebas, o viceversa, se comporta igual que una llave inválida: 401 INVALID_API_KEY.
Formato de la request
Sección titulada «Formato de la request»Content-Type: application/jsonen toda petición con cuerpo. Sin este encabezado, la API no reconoce el cuerpo como JSON.- El cuerpo admite hasta 16 KiB.
- Todas las respuestas llevan
Cache-Control: no-store: no caches una respuesta de la API en un proxy ni en el navegador.
Un cuerpo mal formado responde 400 INVALID_JSON, uno sin Content-Type: application/json responde
415 UNSUPPORTED_MEDIA_TYPE y uno mayor a 16 KiB responde 413 PAYLOAD_TOO_LARGE. Los tres son
errores de tu lado: corrige el request y no lo reintentes automáticamente. Ver el detalle en
Errores.
Límites de tasa
Sección titulada «Límites de tasa»Cada endpoint de comercio tiene su propio límite, por API key:
| Endpoint | Límite |
|---|---|
POST /v1/checkout-sessions |
120 por minuto |
GET /v1/checkout-sessions/{sessionId} |
300 por minuto |
GET /v1/reconciliation/payments.csv |
10 por minuto |
Al exceder el límite, la API responde 429 RATE_LIMITED con un encabezado Retry-After en segundos.
Respeta ese valor antes de reintentar. Exceder el límite no bloquea tu credencial ni afecta a otros comercios.