El SDK de tokenização de PCI Proxy EU permite a los equipas de desarrollo integrar el conformidade PCI DSS directamente en el código de la aplicação, sin necesidade de construir infraestrutura de segurança desde cero. Disponible para los tres lenguajes backend mais utilizados, el SDK gere la autenticação, el encriptação en tránsito e el manejo de errores, dejando al desarrollador únicamente la lógica de negocio. Este artigo muestra los principales patrones de integração con ejemplos concretos.
SDK PCI Proxy EU: estructura e autenticação
El SDK expone un cliente singleton que se inicializa con la API key e el ambiente (sandbox o producção). La autenticação se realiza mediante header Bearer en cada pedido HTTP hacia los endpoints de PCI Proxy EU. El cliente gere automáticamente el retry con backoff exponencial para errores transitorios (timeout, rate limit 429) e lanza excepciones tipadas para errores permanentes como token no encontrado o cartão 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 e publica un SBOM (Software Bill of Materials) para facilitar el conformidade de las políticas de segurança en la cadena de suministro. El changelog documenta los breaking changes e las actualizaciones de los requisitos PCI.
Tokenização en Node.js: ejemplo práctico
En un backend Node.js con Express, el fluxo típico consiste en recibir el token generado por el campo hosted del frontend, llamar al método client.charge(token, amount, currency) e gerir la respuesta. El SDK devuelve un objeto estructurado con el resultado de la autorização, el identificador de la transação e los metadatos necesarios para la conciliação. En caso de rechazo, la respuesta inclui el código ISO de rechazo e un mensaje localizado.
Para los pagos recurrentes, el método client.detokenize(token) recupera una referência al PAN válida para un único cargo hacia el procesador. La referência es de un apenas uso e caduca a los pocos segundos, impidiendo que pueda ser reutilizada por un atacante que interceptara la chamada. El desarrollador nunca recibe el PAN en texto claro: recibe únicamente la referência temporal que el proxy utiliza internamente.
Python e PHP: las mismas funcionalidades, la misma simplicidade
El SDK de Python sigue las convenciones de la librería requests e admite tanto el uso síncrono como asíncrono mediante asyncio. La inicialização se realiza con PCIProxyClient(api_key=os.environ["PCI_PROXY_KEY"]), e todos los métodos aceptan diccionarios Python nativos para los parámetros. La gestão de errores usa excepciones de la jerarquía PCIProxyError, con subclases para errores de autenticação, validação e de red.
Para PHP, el paquete Composer instala automáticamente las dependencias Guzzle para las chamadas HTTP. El cliente usa interfaces PSR-7 e PSR-18, haciéndolo compatible con cualquier framework que siga los estándares PHP-FIG, desde Laravel hasta Symfony. Los métodos estão documentados con PHPDoc completo e el paquete inclui type stubs para el IDE. En ambos lenguajes, la transição de sandbox a producção apenas exige cambiar la variable de ambiente con la clave de producção.
Preguntas frecuentes
El SDK es open source?
El código fuente del SDK está disponible en GitHub con licencia MIT. Cualquier persona pode inspeccionar la implementação, reportar issues e proponer pull requests. El núcleo del vault e del encriptação permanece en el servidor de PCI Proxy EU, mas el código cliente que el desarrollador utiliza en su aplicação es completamente transparente e auditable.
Como gestiono los errores de tokenização en el SDK?
Cada método del SDK pode lanzar excepciones tipadas que corresponden a categorías específicas de error. Los errores de red e timeout se gerem automáticamente mediante el mecanismo de retry. Los errores semánticos como cartão no válida o token caducado se propagan con códigos e mensajes estandarizados que permiten devolver al cliente un mensaje apropiado sin exponer detalles técnicos internos.
El SDK admite la detokenização para cargos recurrentes?
El método de detokenização está concebido específicamente para los pagos recurrentes e las suscripciones. El token se crea una vez durante el primer pago o durante la fase de registro de la cartão, e luego se reutiliza para cada cargo posterior sin que el cliente deba reingresar los dados. El token no tem validade por defecto, mas pode configurarse con una fecha de validade explícita para respetar las políticas de la empresa.
Listo para integrar el SDK de tokenização en tu stack? Accede a la documentação e a la sandbox e entra en producção en pocos días. Descubre PCI Proxy EU.
Precisa de apoio na conformidade PCI?
A nossa equipa ajuda a mapear o seu CDE, escolher o SAQ adequado e implementar tokenização com residência de dados na UE.
Contacte-nosNa prática europeia, cumprir o PCI DSS exige mapear fluxos de PAN, definir o CDE e documentar controlos para auditoria ou SAQ. A tokenização via PCI Proxy EU remove dados sensíveis do ambiente do comerciante, alinhando conformidade PCI e RGPD com residência de dados na UE, especialmente relevante para desenvolvedor.
Na prática europeia, cumprir o PCI DSS exige mapear fluxos de PAN, definir o CDE e documentar controlos para auditoria ou SAQ. A tokenização via PCI Proxy EU remove dados sensíveis do ambiente do comerciante, alinhando conformidade PCI e RGPD com residência de dados na UE, especialmente relevante para desenvolvedor.