Una clave de la API de pagos funciona como una tarjeta de efectivo sin PIN. Quien la envíe puede crear facturas, leer tus datos de pago y, si usas payouts, mover dinero fuera de tu saldo. Por tanto, la seguridad de la API de pagos se reduce a tres hábitos: guardar la clave en tus propios servidores, permitir que la API la acepte solo desde las direcciones de esos servidores y confirmar cada webhook consultando de nuevo el pago antes de actuar.
Esta guía va dirigida a responsables de ingeniería y directores de pagos de proveedores de servicios de pago (PSP), entidades de dinero electrónico (EMI), bancos y comerciantes que conectan una API de pagos con criptomonedas que liquida en euros. Muestra cómo restringir una clave por dirección IP y rango CIDR, dónde debe residir la clave, cómo verificar webhooks y qué controles deben rodear a los payouts. Los ejemplos usan la API y el panel de ItisPay (datos de demostración).
Momentos clave
En resumen
- Una clave de API es una credencial al portador. GitGuardian contabilizó 28,65 millones de secretos nuevos incrustados en el código en commits públicos de GitHub en 2025, así que prevé que una clave pueda filtrarse, no solo cómo mantenerla a salvo.
- Una lista de IP permitidas hace inútil una clave filtrada fuera de tu red. Incluye los rangos IPv4 o IPv6 más pequeños que cubran tus direcciones de salida reales; una lista vacía permite cualquier dirección.
- Un webhook es un aviso, no una prueba. Vuelve a consultar la factura por su ID con tu clave antes de enviar mercancía o abonar en una cuenta.
- Los payouts requieren controles humanos de tu lado: inicio de sesión en dos pasos, IBAN y wallets de beneficiarios guardados, y un segundo aprobador por encima de un importe determinado.
¿Por qué es tan peligrosa una clave de API de pagos filtrada?#
Una clave de API de pagos filtrada es peligrosa porque la clave constituye toda la identidad de tu integración. La API de ItisPay, como la mayoría de las API de pagos, autentica cada solicitud con un único encabezado, Api-key, y la misma autenticación cubre las facturas, los payouts a un IBAN o wallet y las retiradas de criptoactivos a una dirección externa. Por eso la documentación pide que la clave «no quede expuesta en código del lado del cliente ni en repositorios públicos».
En la práctica, las claves se filtran por lugares corrientes: el código, los registros y los chats. Según el State of Secrets Sprawl 2026 de GitGuardian (marzo de 2026), se añadieron 28,65 millones de secretos incrustados en el código en commits públicos de GitHub en 2025, un 34 % más que un año antes. Cuando GitGuardian volvió a probar secretos filtrados en 2022, más del 64 % seguían siendo válidos en enero de 2026. Los equipos publican claves y luego olvidan sustituirlas.
El OWASP API Security Top 10 (2023) sitúa la «Autenticación rota» en segundo lugar y advierte de que «el mecanismo de autenticación es un objetivo fácil para los atacantes, ya que está expuesto a todo el mundo». El Data Breach Investigations Report 2025 de Verizon identifica el abuso de credenciales como el vector de ataque inicial más frecuente, con un 22 %. Una cadena secreta por sí sola es una defensa débil, así que el resto de esta guía añade capas que siguen funcionando una vez que la cadena se ha filtrado.
¿Cómo protege una lista de IP permitidas una clave de API?#
Una lista de IP permitidas, llamada a veces lista blanca de IP, protege la clave vinculándola a lugares además de a una cadena. La API acepta la clave solo cuando la solicitud llega desde una dirección que hayas incluido en la lista; una copia de la clave en el portátil de un desarrollador, en un registro de CI o en un sitio de pegado no funciona.
En el panel de ItisPay, el ajuste está en Projects, luego en Settings y después en Security, en el campo API Allowed IPs. El campo acepta una lista separada por comas de direcciones individuales y bloques CIDR. Su texto de ayuda dice: «Deja vacío para permitir todas las IP. Se admiten IPv4 e IPv6.» La misma lista puede configurarse al crear un proyecto mediante la API, en el campo api_allowed_ips, y una entrada no válida, como 256.256.256.256, se rechaza con un error de validación en lugar de guardarse.
El valor predeterminado vacío importa. Un proyecto nuevo acepta su clave desde cualquier lugar hasta que alguien rellena el campo, así que incluye ese paso en la lista de puesta en producción, no en la de cosas que ordenar más adelante. Los valores de demostración de la captura, 203.0.113.10 y 198.51.100.0/24, proceden de rangos que la RFC 5737 reserva para documentación; tu lista contendrá tus propias direcciones públicas. Cada proyecto tiene su propia clave de 64 caracteres y su propia lista, así que producción puede limitarse a dos o tres servidores mientras un proyecto de prueba acepta un conjunto más amplio.
¿Cómo se escriben los rangos CIDR para IPv4 e IPv6?#
Escribe el rango más pequeño que cubra cada dirección que tus servidores usan realmente para llegar a la API. La mayoría de los problemas con listas de permitidos vienen de un rango demasiado amplio o de una ruta de salida que alguien olvidó.
Cómo leer un prefijo#
Un bloque CIDR es una dirección seguida de una barra y una longitud de prefijo. La RFC 4632 define la longitud del prefijo como el número de bits significativos: 192.168.99.0/24 fija los primeros 24 bits y deja libres 8, lo que da 256 direcciones. Cada bit que quitas al prefijo duplica el bloque. Una /32 es una dirección IPv4, una /29 son 8, una /24 son 256 y una /16 son 65 536.
IPv6 funciona igual con 128 bits. Una /128 es una única dirección. La RFC 4291 fija la parte de interfaz de la mayoría de las direcciones IPv6 en 64 bits, así que la red de un servidor suele ser una /64 y el host puede cambiar su dirección dentro de ella, por ejemplo cuando el sistema operativo genera direcciones temporales. Si la dirección IPv6 de tu host cambia y esa /64 es solo tuya, incluye la /64 en lugar de una única /128. El rango de documentación para ejemplos de IPv6 es 2001:db8::/32 (RFC 3849), así que nunca lo copies en una lista de permitidos real.
Cómo encontrar tu dirección de salida real#
La dirección que importa es la que ve la API, no la que tu servidor declara sobre sí mismo. Detrás de una puerta de enlace NAT en la nube o de un cortafuegos corporativo, muchas máquinas comparten una o dos direcciones públicas. Las funciones sin servidor (serverless) suelen salir desde un grupo compartido salvo que las enrutes a través de una salida fija. Comprueba desde cada entorno llamando a un servicio de «cuál es mi IP» o lee la dirección de origen en los registros de tu cortafuegos, y luego incluye exactamente esa.
| Configuración | Qué incluir en la lista | Veredicto |
|---|---|---|
| Un servidor con una dirección IPv4 pública estática | Esa dirección como /32 o sin máscara | Funciona |
| Varios servidores detrás de una puerta de enlace NAT en la nube | Las direcciones públicas de la puerta de enlace NAT | Funciona |
| Host IPv6 con direcciones cambiantes | La /64 del host, si nadie más la utiliza | Depende |
| Red de oficina para pruebas manuales | La dirección fija de la oficina, si el proveedor la garantiza | Depende |
| Funciones serverless sin salida fija | Enrútalas primero a través de una NAT con dirección estática | No |
| Todo el rango regional de un proveedor de nube | Nada; también incluye a otros clientes | No |
Antes de guardar un cambio, añade primero la nueva dirección, despliega, confirma que el tráfico fluye y solo entonces elimina la antigua. Guardar una lista que omite tus servidores activos bloquea tu propio proceso de pago.
¿Dónde debe estar la clave de API y quién la ve?#
La clave debe estar en tus servidores, en un almacén de secretos, y en ningún otro lugar. Nunca la incluyas en una página del navegador ni en una aplicación móvil, porque cualquiera puede leerla allí. Tampoco la pongas en las URL: la OWASP REST Security Cheat Sheet advierte de que una clave en una URL puede quedar registrada en los logs del servidor web. Tu página de pago se comunica con tu back end; el back end se comunica con la API de pagos.
Carga la clave desde un gestor de secretos o desde variables de entorno al arrancar, no desde un archivo de configuración del repositorio. Si alojas código en GitHub, activa la protección de push: según la documentación de GitHub, cuando «detecta un posible secreto durante un intento de push, bloqueará el push».
Usa una clave por entorno. Cada proyecto de ItisPay tiene su propia clave y su propia lista de IP permitidas, así que separar los proyectos de producción y de staging significa que una clave de staging filtrada no puede afectar a los pagos reales. Limita quién puede ver la clave de producción. Las directrices de la EBA de 2019 sobre seguridad de las TIC establecen la regla de «necesidad de conocer» con «derechos mínimos de acceso», incluidos los usuarios técnicos; desde 2025, DORA extiende esa obligación a la mayoría de las entidades de pago.
Después, documenta cómo sustituirías la clave, antes de necesitarlo. La OWASP Cryptographic Storage Cheat Sheet recomienda rotar las claves tras un periodo determinado y siempre que se sospeche un compromiso, y asegurarse de que «el código y los procesos necesarios para rotar una clave estén implantados antes de que se necesiten».
¿Cómo debes verificar los webhooks de una API de pagos?#
Trata un webhook como un aviso de que algo ha cambiado, nunca como prueba de que te han pagado. Cualquiera que conozca tu URL de callback puede enviarte un mensaje falso de «completado». El patrón seguro consiste en leer la factura de nuevo desde la API con tu propia clave y actuar según lo que devuelva la API.
Al crear una factura de ItisPay, el campo callback_url define la dirección para las actualizaciones de estado. Cuando llega un webhook, toma de él el ID de la factura, llama a GET sobre la factura por ID y envía o abona el importe solo si esa respuesta muestra el estado que esperas y el importe que fijaste. La documentación describe este endpoint como un recurso que devuelve el estado del pago y los detalles de la blockchain «para mostrar a los usuarios o para verificación».
Algunas reglas mantienen el manejador limpio:
- Acepta webhooks solo por HTTPS y rechaza el HTTP sin cifrar.
- Haz el manejador idempotente. Guarda el ID de cada factura procesada y su estado, y omite las repeticiones, porque los proveedores reenvían los avisos.
- Responde rápido y realiza el trabajo en una cola, para que una base de datos lenta no provoque reintentos.
- Si un proveedor firma sus webhooks con HMAC, un hash con clave definido en la RFC 2104, recalcula la firma y compárala con una función de tiempo constante. La OWASP Webhook Security Cheat Sheet es tajante: «Nunca use ==: filtra información de tiempos y puede convertir el endpoint en un oráculo de firma». Rechaza los mensajes cuyo timestamp firmado sea demasiado antiguo.
Prueba antes de la puesta en producción. ItisPay dispone de un endpoint que simula un cambio de estado en una factura de prueba real, y de otro que reenvía el último webhook de una factura o de un ID de pedido, para que puedas comprobar los reintentos y los duplicados sin dinero real.
¿Cómo bloquear los pagos salientes y el acceso al panel?#
Los pagos salientes son el punto donde una clave robada se convierte en dinero perdido, así que añade controles humanos a su alrededor. A través del endpoint de pagos salientes de ItisPay, un pago en moneda fiduciaria va a un IBAN del beneficiario y un pago en cripto a una dirección de wallet, ambos desde tu saldo disponible. La API hace lo que dice la solicitud; decidir si una solicitud es legítima es responsabilidad tuya.
Controles que funcionan en tu lado:
- Inicio de sesión en dos pasos para todos los que tengan acceso al panel o a los pagos salientes. La legislación de pagos de la UE ya usa esta idea para los usuarios de servicios de pago: las normas PSD2 sobre autenticación reforzada de cliente exigen al menos dos elementos independientes de conocimiento, posesión e inherencia. Aplica el mismo estándar a tu propio personal.
- Beneficiarios guardados. Mantén tu propia lista de IBAN y direcciones de wallet aprobados, y permite que tu servicio de pagos envíe únicamente a entradas de esa lista. Un nuevo beneficiario pasa por una aprobación aparte, idealmente con un periodo de espera.
- Un segundo aprobador por encima de un umbral. Una persona prepara y otra aprueba. Fija el umbral según tu propio apetito de riesgo.
- Un servicio de pagos salientes independiente. Ejecuta los pagos salientes desde un servicio con su propia dirección fija en la lista de IP permitidas, separado de los servidores de pago que crean las facturas.
| Control | Qué impide | Veredicto |
|---|---|---|
| Lista blanca de IP en la clave | Uso de una clave filtrada desde fuera de tu red | Funciona |
| Clave solo en el servidor | Robo de la clave desde navegadores, apps y repositorios | Funciona |
| Releer la factura tras un webhook | Avisos falsos de «pagado» | Funciona |
| Beneficiarios guardados y segundo aprobador | Pagos al IBAN o a la wallet de un atacante | Funciona |
| Cualquiera de estas medidas por sí sola frente a un servidor comprometido incluido en la lista | Robo por parte de alguien que ya está dentro | No |
¿Qué exigen DORA y PCI DSS en el acceso a la API?#
Si es una entidad financiera regulada de la UE, estos controles no son complementos opcionales. El Reglamento de Resiliencia Operativa Digital (DORA, Reglamento (UE) 2022/2554) es de aplicación desde el 17 de enero de 2025, según la EBA. Su artículo 9 exige a las entidades que «establezcan políticas que limiten el acceso físico o lógico» a los activos de TIC y que «establezcan políticas y protocolos para mecanismos de autenticación sólida». Una clave incluida en lista blanca, solo en el servidor y con un plan de rotación es el tipo de evidencia que un auditor pide ver.
PCI DSS cubre los datos de tarjetas, no las facturas cripto. Si el mismo equipo también gestiona pagos con tarjeta, el requisito 8.4.2 exige autenticación multifactor en todo acceso al entorno de datos del titular de la tarjeta, y los requisitos con fecha de aplicación futura de la versión 4.0 pasaron a ser obligatorios el 31 de marzo de 2025.
¿Dónde dejan de funcionar los controles de seguridad de la API de pagos?#
Estos controles reducen las vías de entrada. Por sí solos no hacen segura una integración. Incluso para los emisores de webhooks, la hoja de referencia de OWASP sobre webhooks describe la lista blanca de IP como una «capa extra únicamente», porque «una IP de salida compartida no es prueba de identidad».
Dónde no ayuda
- Un servidor hackeado incluido en la lista blanca. El atacante envía solicitudes desde una dirección de confianza con la clave real.
- Direcciones de salida compartidas. Si otros inquilinos salen a la nube desde la misma dirección NAT, la lista blanca no puede distinguirlos de ti.
- Una contraseña robada del panel sin inicio de sesión en dos pasos. El atacante se salta la API por completo.
- Datos personales en los campos de la factura. El endpoint público de facturas de ItisPay devuelve todos los detalles de las facturas abiertas sin clave, así que no incluyas nombres ni correos de clientes en el nombre del pedido.
¿Cómo se empieza una integración segura en una tarde?#
Puedes terminar la parte técnica de una integración segura en una tarde si sigues un orden fijo. Los pasos siguientes usan ItisPay; el mismo orden sirve con cualquier proveedor.
- Crea un proyecto de prueba y un proyecto de producción independiente, cada uno con su propia clave.
- Guarda ambas claves en tu gestor de secretos y cárgalas solo en el servidor.
- Localiza la dirección de salida pública de cada entorno e introdúcela en API Allowed IPs.
- Crea una factura desde el backend: POST a https://api.itispay.com/api/v1/invoices con la cabecera Api-key, un order_id único, fiat_amount con fiat_currency EUR, la criptomoneda en currency y tu callback_url.
- Crea el manejador de webhooks: solo HTTPS, idempotente, y vuelve a leer la factura por ID antes de cualquier acción.
- Ejecuta la simulación de webhook para cada estado que gestiones y después el endpoint de reenvío para probar duplicados.
- Activa los pagos al final, con beneficiarios guardados y un segundo aprobador.
Para empezar rápido, el asistente Ask AI del panel escribe código de ejemplo bajo petición, como una llamada para crear facturas en Node.js con la cabecera Api-key ya incluida. Trátalo como un borrador: verifica los nombres de los campos con la referencia de la API antes de desplegarlo, porque la referencia, y no un ejemplo generado, es el contrato. ItisPay también publica un cliente oficial de TypeScript en npm, @itispay/typescript-client.
Si lo integras en una arquitectura más amplia de orquestación de pagos, asigna a cada proveedor su propia clave, lista blanca y manejador de webhooks. El mismo registro leído de nuevo por ID también alimenta la conciliación de pagos cripto para tu equipo financiero.
Si quieres aceptar pagos en stablecoins y recibir euros sin construir la infraestructura tú mismo, ItisPay ofrece la API, facturación, webhooks y conciliación, así como la primera capa de seguridad de la API de pagos: claves que puedes restringir a tus propias direcciones IP. La licencia, el KYC y la liquidación en tu IBAN se gestionan a través de nuestro socio con licencia en la UE, que combina un proveedor de servicios de criptoactivos (CASP) y una entidad de pago, y la mayoría de los equipos pasan del KYB a la primera transacción en menos de una semana.
Este artículo tiene fines únicamente informativos y no constituye asesoramiento jurídico ni regulatorio.
