Saltar al contenido principal

​
Visión General

La autenticación de sandbox usa las mismas dos capas que producción:
  1. Certificado X.509 (mTLS) — entregado por NTX Pay en el onboarding.
  2. OAuth 2.0 client_credentials — clientId + clientSecret recibidos en el signup.
En conjunto, devuelven un JWT (validez de 10 minutos) usado en los demás endpoints como Authorization: Bearer ....
Las credenciales de sandbox son distintas de las de producción. Si usas credenciales de producción contra https://sandbox.mx.ntxpay.com, recibirás 401. El contrato HTTP es idéntico — lo que cambia es el par certificado + clientId/clientSecret.

​
Obtener Token

​
POST /api/auth/token

curl -X POST https://sandbox.mx.ntxpay.com/api/auth/token \
  -H "X-SSL-Client-Cert: $ENCODED_CERT" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "qr-93-550e8400",
    "clientSecret": "a1b2c3d4e5f6g7h8"
  }'

​
Response (201)

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 600,
  "scope": "email profile"
}

​
Usar el Token

En una cuenta sandbox, cualquier llamada autenticada simula el pipeline completo sin mover dinero real: 
curl -X POST https://sandbox.mx.ntxpay.com/api/spei/cash-out \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCentavos": 15000,
    "destinationClabe": "012180001234567890",
    "beneficiaryName": "Maria Lopez",
    "externalId": "test-001"
  }'
La respuesta siempre es 201 Created con status: PENDING. El resultado final (confirmación o falla) llega vía webhook tras ~1 segundo. Mira Escenarios para forzar resultados específicos.

​
Renovación

El token expira en 10 minutos (600s). No hay refresh token — genera uno nuevo vía POST /api/auth/token antes de que expire.
Bajo alta carga, genera un token por worker y renueva cada ~8 minutos para evitar 401 por expiración.

​
Errores Comunes

CódigoCausaSolución
400X-SSL-Client-Cert ausenteConfigura NGINX/ALB para reenviar el certificado
401clientId/clientSecret inválidoVerifica las credenciales; confirma que estás usando las de sandbox
401Certificado expirado/revocadoSolicita renovación a NTX Pay

​
Documentación detallada

Para el paso a paso completo (codificación del certificado, ejemplos en múltiples lenguajes, etc.) mira Autenticación en la guía general — la única diferencia es la base URL https://sandbox.mx.ntxpay.com.