El SDK de tokenización de PCI Proxy EU permite a los equipos de desarrollo integrar el cumplimiento PCI DSS directamente en el código de la aplicación, sin necesidad de construir infraestructura de seguridad desde cero. Disponible para los tres lenguajes backend más utilizados, el SDK gestiona la autenticación, el cifrado en tránsito y el manejo de errores, dejando al desarrollador únicamente la lógica de negocio. Este artículo muestra los principales patrones de integración con ejemplos concretos.
SDK PCI Proxy EU: estructura y autenticación
El SDK expone un cliente singleton que se inicializa con la API key y el entorno (sandbox o producción). La autenticación se realiza mediante header Bearer en cada solicitud HTTP hacia los endpoints de PCI Proxy EU. El cliente gestiona automáticamente el retry con backoff exponencial para errores transitorios (timeout, rate limit 429) y lanza excepciones tipadas para errores permanentes como token no encontrado o tarjeta caducada.
La estructura del paquete sigue las convenciones de cada lenguaje: módulos CommonJS/ESM para Node.js, paquete PyPI para Python, paquete Composer para PHP. Cada versión está firmada y publica un SBOM (Software Bill of Materials) para facilitar el cumplimiento de las políticas de seguridad en la cadena de suministro. El changelog documenta los breaking changes y las actualizaciones de los requisitos PCI.
Tokenización en Node.js: ejemplo práctico
En un backend Node.js con Express, el flujo típico consiste en recibir el token generado por el campo hosted del frontend, llamar al método client.charge(token, amount, currency) y gestionar la respuesta. El SDK devuelve un objeto estructurado con el resultado de la autorización, el identificador de la transacción y los metadatos necesarios para la conciliación. En caso de rechazo, la respuesta incluye el código ISO de rechazo y un mensaje localizado.
Para los pagos recurrentes, el método client.detokenize(token) recupera una referencia al PAN válida para un único cargo hacia el procesador. La referencia es de un solo uso y caduca a los pocos segundos, impidiendo que pueda ser reutilizada por un atacante que interceptara la llamada. El desarrollador nunca recibe el PAN en texto claro: recibe únicamente la referencia temporal que el proxy utiliza internamente.
Python y PHP: las mismas funcionalidades, la misma simplicidad
El SDK de Python sigue las convenciones de la librería requests y admite tanto el uso síncrono como asíncrono mediante asyncio. La inicialización se realiza con PCIProxyClient(api_key=os.environ["PCI_PROXY_KEY"]), y todos los métodos aceptan diccionarios Python nativos para los parámetros. La gestión de errores usa excepciones de la jerarquía PCIProxyError, con subclases para errores de autenticación, validación y de red.
Para PHP, el paquete Composer instala automáticamente las dependencias Guzzle para las llamadas HTTP. El cliente usa interfaces PSR-7 y PSR-18, haciéndolo compatible con cualquier framework que siga los estándares PHP-FIG, desde Laravel hasta Symfony. Los métodos están documentados con PHPDoc completo y el paquete incluye type stubs para el IDE. En ambos lenguajes, la transición de sandbox a producción solo requiere cambiar la variable de entorno con la clave de producción.
Preguntas frecuentes
¿El SDK es open source?
El código fuente del SDK está disponible en GitHub con licencia MIT. Cualquier persona puede inspeccionar la implementación, reportar issues y proponer pull requests. El núcleo del vault y del cifrado permanece en el servidor de PCI Proxy EU, pero el código cliente que el desarrollador utiliza en su aplicación es completamente transparente y auditable.
¿Cómo gestiono los errores de tokenización en el SDK?
Cada método del SDK puede lanzar excepciones tipadas que corresponden a categorías específicas de error. Los errores de red y timeout se gestionan automáticamente mediante el mecanismo de retry. Los errores semánticos como tarjeta no válida o token caducado se propagan con códigos y mensajes estandarizados que permiten devolver al cliente un mensaje apropiado sin exponer detalles técnicos internos.
¿El SDK admite la detokenización para cargos recurrentes?
El método de detokenización está diseñado específicamente para los pagos recurrentes y las suscripciones. El token se crea una vez durante el primer pago o durante la fase de registro de la tarjeta, y luego se reutiliza para cada cargo posterior sin que el cliente deba reingresar los datos. El token no tiene caducidad por defecto, pero puede configurarse con una fecha de caducidad explícita para respetar las políticas de la empresa.
¿Listo para integrar el SDK de tokenización en tu stack? Accede a la documentación y a la sandbox y entra en producción en pocos días. Descubre PCI Proxy EU.