Saltar al contenido principal

​
Visión General

La API NTX Pay México usa autenticación en dos capas:
  1. Certificado X.509 (mTLS) — entregado por NTX Pay en el onboarding, comprueba la identidad del servidor cliente.
  2. OAuth 2.0 client_credentials — clientId + clientSecret recibidos en el signup, validados junto con el certificado.
La combinación retorna un JWT (validez 10 minutos) usado en los demás endpoints como Authorization: Bearer ....

​
Endpoint

​
POST /api/auth/token

​
Headers Obligatorios

X-SSL-Client-Cert: <PEM-URL-encoded>
Content-Type: application/json
El X-SSL-Client-Cert típicamente lo inyecta NGINX/ALB con el certificado URL-encoded: 
proxy_set_header X-SSL-Client-Cert $ssl_client_escaped_cert;
En desarrollo, haz el URL-encode manual: 
ENCODED_CERT=$(cat client.cert.pem | python3 -c "import sys,urllib.parse; print(urllib.parse.quote(sys.stdin.read()))")

​
Request

curl -X POST https://api.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"
}

​
Usando el Token

Incluye el access_token en todas las requests autenticadas: 
curl -X GET https://api.ntxpay.com/api/balance \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Renovación

El token expira en 10 minutos (600s). Repite el paso 1 antes de expirar — no hay refresh token.
No hagas caché del token entre procesos sin mecanismo de invalidación. 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 forwardear el certificado
400PEM malformadoVerifica que el certificado comience con -----BEGIN CERTIFICATE-----
401clientId/clientSecret inválidoRevisa las credenciales (sin espacios)
401Certificado expirado/revocadoSolicita renovación a NTX Pay

​
Ejemplo Node.js

import fs from 'fs';
import axios from 'axios';

const cert = fs.readFileSync('client.cert.pem', 'utf-8');
const encodedCert = encodeURIComponent(cert);

async function getToken(): Promise<string> {
  const { data } = await axios.post(
    'https://api.ntxpay.com/api/auth/token',
    {
      clientId: process.env.NTXPAY_CLIENT_ID,
      clientSecret: process.env.NTXPAY_CLIENT_SECRET,
    },
    {
      headers: {
        'X-SSL-Client-Cert': encodedCert,
        'Content-Type': 'application/json',
      },
    },
  );
  return data.access_token;
}

​
Próximos Pasos

Quickstart

Flujo completo (signup → token → transacción)

Consulta de Saldo

Usa el token para consultar el saldo