Ir al contenido

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.

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.

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.

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.

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.

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.

  • Content-Type: application/json en 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.

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.