Skip to main content

​
Overview

Sandbox authentication uses the same two layers as production:
  1. X.509 certificate (mTLS) — issued by NTX Pay at onboarding.
  2. OAuth 2.0 client_credentials — clientId + clientSecret received during signup.
Together they return a JWT (10-minute validity) used on the remaining endpoints as Authorization: Bearer ....
Sandbox credentials are distinct from production. If you use production credentials against https://sandbox.mx.ntxpay.com, you will get 401. The HTTP contract is identical — what changes is the certificate + clientId/clientSecret pair.

​
Get a 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"
}

​
Use the Token

On a sandbox account, any authenticated call simulates the full pipeline without moving real money: 
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"
  }'
The response is always 201 Created with status: PENDING. The final outcome (confirmation or failure) arrives via webhook ~1 second later. See Scenarios to force specific outcomes.

​
Renewal

The token expires in 10 minutes (600s). There is no refresh token — get a new one via POST /api/auth/token before expiration.
Under high load, mint a token per worker and renew every ~8 minutes to avoid 401 due to expiration.

​
Common Errors

CodeCauseFix
400X-SSL-Client-Cert missingConfigure NGINX/ALB to forward the certificate
401Invalid clientId/clientSecretDouble-check credentials; confirm you are using the sandbox ones
401Certificate expired/revokedRequest renewal from NTX Pay

​
Detailed documentation

For the full step-by-step (certificate encoding, examples in multiple languages, etc.) see Authentication in the main guide — the only difference is the base URL https://sandbox.mx.ntxpay.com.