Pular para o conteúdo principal

​
Visão Geral

A autenticação em sandbox usa as mesmas duas camadas que produção:
  1. Certificado X.509 (mTLS) — entregue pelo NTX Pay no onboarding.
  2. OAuth 2.0 client_credentials — clientId + clientSecret recebidos no signup.
Em conjunto, retornam um JWT (validade 10 minutos) usado nos demais endpoints como Authorization: Bearer ....
As credenciais de sandbox são distintas das de produção. Se você usar credenciais de produção contra https://sandbox.mx.ntxpay.com, receberá 401. O contrato HTTP é idêntico — o que muda é o par certificado + clientId/clientSecret.

​
Obter 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 o Token

Em uma conta sandbox, qualquer chamada autenticada simula um pipeline completo sem mover dinheiro 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"
  }'
A resposta é sempre 201 Created com status: PENDING. O resultado final (confirmação ou falha) chega via webhook após ~1 segundo. Veja Cenários para forçar resultados específicos.

​
Renovação

O token expira em 10 minutos (600s). Não há refresh token — gere um novo via POST /api/auth/token antes de expirar.
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
401clientId/clientSecret inválidoReconfira credenciais; certifique-se de estar usando as de sandbox
401Certificado expirado/revogadoSolicite renovação ao NTX Pay

​
Documentação detalhada

Para o passo a passo completo (encoding do certificado, exemplos em múltiplas linguagens, etc.) veja Autenticação no guia geral — a única diferença é a base URL https://sandbox.mx.ntxpay.com.