En esta página

Autenticación

Aprende a autenticar tus solicitudes a la API de iion pay usando API Keys.

API Keys

iion pay 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

Entra al panel de negocios

Inicia sesión en el panel de negocios de iion pay con tu cuenta de comercio. Ahí creas y revocas tus API Keys.

Ve a Integraciones → API keys

En el menú lateral, abre "Integraciones" y selecciona "API keys".

Crea una nueva key

Haz clic en "Crear una 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.

Permisos de una API Key

Cada API Key guarda una lista de permisos. Estos son los permisos que puede tener una key:

Permiso Descripción
collect:create Crear órdenes de cobro
collect:read Consultar órdenes de cobro
payout:create Crear pagos salientes
stats:read Consultar estadísticas
memberships:read Consultar membresías
memberships:write Crear y modificar membresías

Una key nueva tiene collect:create y collect:read. Si tu negocio tiene la verificación aprobada y los pagos salientes habilitados, la key nueva también tiene payout:create.

Los permisos de cobros aún no se aplican
Por ahora, hoy la API no bloquea las rutas de cobros según estos permisos. Trata cada API Key como una credencial con acceso completo y guárdala con el mismo cuidado.

IPs permitidas

En el panel de negocios puedes guardar una lista de IPs permitidas para cada API Key. La lista acepta hasta 20 IPs exactas, en formato IPv4 o IPv6. No acepta rangos CIDR (por ejemplo, 203.0.113.0/24). Una lista vacía significa que la key acepta solicitudes desde cualquier IP.

Por ahora, esta lista hoy no restringe las solicitudes: la API acepta la key desde cualquier IP aunque la lista tenga valores. Si la configuras desde ahora, usa solo las IPs de salida de tus servidores.

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.iionpay.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, la API responde 401. Estos errores no traen error.code: se distinguen por message.

message HTTP Status Descripción
API Key and Secret are required 401 Faltan los headers X-Api-Key o X-Api-Secret
Invalid API credentials 401 El API Key o Secret son inválidos, o la llave está revocada
Merchant account is not active 401 La cuenta del comercio no está activa

Ejemplo de respuesta de error

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API credentials",
  "error": {
    "message": "Invalid API credentials",
    "error": "Unauthorized",
    "statusCode": 401
  },
  "timestamp": "2026-10-30T16:57:11.300Z",
  "path": "/api/v1/collect"
}

El formato completo de los errores está en Manejo de Errores.

Revocar una API Key

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

  1. En el panel de negocios, ve a Integraciones → 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
IION_API_KEY=tu_api_key
IION_API_SECRET=tu_api_secret

// app.js
const apiKey = process.env.IION_API_KEY;
const apiSecret = process.env.IION_API_SECRET;

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

# app.py
import os
import requests

api_key = os.environ['IION_API_KEY']
api_secret = os.environ['IION_API_SECRET']

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

// app.php
<?php
$apiKey = getenv('IION_API_KEY');
$apiSecret = getenv('IION_API_SECRET');

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