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 |
Crear una API Key
Inicia sesión en el panel de negocios de iion pay con tu cuenta de comercio. Ahí creas y revocas tus API Keys.
En el menú lateral, abre "Integraciones" y selecciona "API keys".
Haz clic en "Crear una key" y asigna un nombre descriptivo (ej: "Producción", "Staging").
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.
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:
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:
- En el panel de negocios, ve a Integraciones → API keys
- Encuentra la key que deseas revocar
- Haz clic en el botón "Revocar"
- Confirma la acción
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',
],
// ...
]);