Autenticación

Aprende a autenticar tus solicitudes a la API de NIIO Payments usando API Keys.

API Keys

NIIO utiliza un sistema de autenticación basado en API Keys para identificar y autorizar las solicitudes de tu aplicación. Cada merchant puede generar múltiples API Keys desde el dashboard.

Cada API Key consiste en dos partes:

Componente Header Descripción
API Key X-Api-Key Identificador público de tu aplicación
API Secret X-Api-Secret Clave secreta para autenticar solicitudes
Mantén tu API Secret seguro
El API Secret solo se muestra una vez al crear la key. Si lo pierdes, deberás crear una nueva API Key. Nunca compartas tu API Secret ni lo incluyas en código del lado del cliente.

Crear una API Key

Solicita tus credenciales

Solicita tus credenciales de API (API Key y API Secret) a tu contacto en NIIO. Aún no existe un panel self-service para generarlas.

Ve a Configuración → API Keys

En el menú lateral, navega a la sección de configuración y selecciona "API Keys".

Crea una nueva key

Haz clic en "Crear API Key" y asigna un nombre descriptivo (ej: "Producción", "Staging").

Guarda tus credenciales

Copia y guarda de forma segura tanto el API Key como el API Secret. El secret no se mostrará de nuevo.

Autenticar solicitudes

Incluye ambas credenciales en los headers de cada solicitud:

Headers requeridos 
X-Api-Key: tu_api_key
X-Api-Secret: tu_api_secret
Content-Type: application/json

Ejemplo de solicitud autenticada

curl -X GET https://api.prod.niiopay.com/api/v1/collect/clxyz123abc456def \
  -H "X-Api-Key: tu_api_key" \
  -H "X-Api-Secret: tu_api_secret" \
  -H "Content-Type: application/json"

Errores de autenticación

Si la autenticación falla, recibirás uno de estos errores:

Código HTTP Status Descripción
MISSING_CREDENTIALS 401 Faltan los headers X-Api-Key o X-Api-Secret
INVALID_CREDENTIALS 401 El API Key o Secret son inválidos
MERCHANT_NOT_ACTIVE 401 La cuenta del merchant no está activa

Ejemplo de respuesta de error

{
  "success": false,
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Invalid API credentials",
    "details": {}
  }
}

Revocar una API Key

Si sospechas que tu API Key ha sido comprometida, revócala inmediatamente:

  1. Ve a Dashboard → Configuración → API Keys
  2. Encuentra la key que deseas revocar
  3. Haz clic en el botón "Revocar"
  4. Confirma la acción
Acción irreversible
Una vez revocada, la API Key dejará de funcionar inmediatamente. Asegúrate de actualizar tu aplicación con una nueva key antes de revocar la anterior.

Buenas prácticas

  • Usa variables de entorno: Nunca incluyas credenciales directamente en tu código fuente.
  • Rota tus keys periódicamente: Crea nuevas keys y revoca las antiguas cada cierto tiempo.
  • Una key por ambiente: Usa keys diferentes para desarrollo, staging y producción.
  • Solo backend: Las llamadas a la API deben hacerse siempre desde tu servidor, nunca desde el frontend.

Ejemplo con variables de entorno

// .env
NIIO_API_KEY=tu_api_key
NIIO_API_SECRET=tu_api_secret

// app.js
const apiKey = process.env.NIIO_API_KEY;
const apiSecret = process.env.NIIO_API_SECRET;

const response = await fetch('https://api.prod.niiopay.com/api/v1/collect', {
  method: 'POST',
  headers: {
    'X-Api-Key': apiKey,
    'X-Api-Secret': apiSecret,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(orderData),
});
# .env
NIIO_API_KEY=tu_api_key
NIIO_API_SECRET=tu_api_secret

# app.py
import os
import requests

api_key = os.environ['NIIO_API_KEY']
api_secret = os.environ['NIIO_API_SECRET']

response = requests.post(
    'https://api.prod.niiopay.com/api/v1/collect',
    headers={
        'X-Api-Key': api_key,
        'X-Api-Secret': api_secret,
        'Content-Type': 'application/json',
    },
    json=order_data
)
// .env
NIIO_API_KEY=tu_api_key
NIIO_API_SECRET=tu_api_secret

// app.php
<?php
$apiKey = getenv('NIIO_API_KEY');
$apiSecret = getenv('NIIO_API_SECRET');

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.prod.niiopay.com/api/v1/collect',
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . $apiKey,
        'X-Api-Secret: ' . $apiSecret,
        'Content-Type: application/json',
    ],
    // ...
]);