Pular para o conteúdo principal

​
Visão Geral

A API NTX Pay México usa autenticação em duas camadas:
  1. Certificado — entregue pelo NTX Pay no onboarding, comprova a identidade do servidor cliente.
  2. OAuth 2.0 client_credentials — clientId + clientSecret recebidos no signup, validados em conjunto com o certificado.
A combinação retorna um JWT (validade 10 minutos) usado nos demais endpoints como Authorization: Bearer ....

​
Endpoint

​
POST /api/auth/token

​
Headers Obrigatórios

X-SSL-Client-Cert: <PEM-URL-encoded>
Content-Type: application/json
O X-SSL-Client-Cert é tipicamente injetado pelo NGINX/ALB com o certificado URL-encoded: 
proxy_set_header X-SSL-Client-Cert $ssl_client_escaped_cert;
Em desenvolvimento, faça o URL-encode manualmente: 
ENCODED_CERT=$(cat client.cert.pem | python3 -c "import sys,urllib.parse; print(urllib.parse.quote(sys.stdin.read()))")

​
Request

curl -X POST https://sandbox.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 o Token

Inclua o access_token em todas as requisições autenticadas: 
curl -X GET https://sandbox.ntxpay.com/api/spei/transaction/order-abc-123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Renovação

O token expira em 10 minutos (600s). Repita o passo 1 antes de expirar — não há refresh token.
Não faça cache do token entre processos sem mecanismo de invalidação. Em alta carga, gere um token por worker e renove a cada ~8 minutos para evitar 401 por expiração.

​
Erros Comuns

CódigoCausaSolução
400X-SSL-Client-Cert ausenteConfigure NGINX/ALB para repassar o certificado
400PEM malformadoVerifique se o certificado começa com -----BEGIN CERTIFICATE-----
401clientId/clientSecret inválidoReconfira as credenciais (sem espaços extras)
401Certificado expirado/revogadoSolicite renovação ao NTX Pay

​
Exemplos de Código

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://sandbox.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 Passos

Testes em Sandbox

Use o header X-Sandbox-Scenario para simular sucesso, falha e atraso nos webhooks

Criar Cobrança SPEI

Aplique o token Bearer e faça sua primeira cobrança SPEI Cash-In