O SDK de tokenização da PCI Proxy EU permite às equipas de desenvolvimento integrar a conformidade PCI DSS diretamente no código da aplicação, sem necessidade de construir infraestrutura de segurança de raiz. Disponível para as três linguagens backend mais utilizadas, o SDK gere a autenticação, a encriptação em trânsito e o tratamento de erros, deixando ao programador apenas a lógica de negócio. Este artigo apresenta os principais padrões de integração com exemplos concretos.
SDK PCI Proxy EU: estrutura e autenticação
O SDK expõe um cliente singleton que é inicializado com a API key e o ambiente (sandbox ou produção). A autenticação é realizada através de um cabeçalho Bearer em cada pedido HTTP para os endpoints da PCI Proxy EU. O cliente gere automaticamente a repetição com backoff exponencial para erros transitórios (timeout, rate limit 429) e lança exceções tipadas para erros permanentes como token não encontrado ou cartão expirado.
A estrutura do pacote segue as convenções de cada linguagem: módulos CommonJS/ESM para Node.js, pacote PyPI para Python, pacote Composer para PHP. Cada versão é assinada e publica um SBOM (Software Bill of Materials) para facilitar a conformidade com as políticas de segurança na cadeia de fornecimento. O changelog documenta as breaking changes e as atualizações dos requisitos PCI.
Tokenização em Node.js: exemplo prático
Num backend Node.js com Express, o fluxo típico consiste em receber o token gerado pelo campo hosted do frontend, chamar o método client.charge(token, amount, currency) e gerir a resposta. O SDK devolve um objeto estruturado com o resultado da autorização, o identificador da transação e os metadados necessários para a reconciliação. Em caso de recusa, a resposta inclui o código ISO de recusa e uma mensagem localizada.
Para pagamentos recorrentes, o método client.detokenize(token) recupera uma referência ao PAN válida para um único débito junto do processador. A referência é de utilização única e expira em poucos segundos, impedindo que possa ser reutilizada por um atacante que intercete a chamada. O programador nunca recebe o PAN em texto simples: recebe apenas a referência temporal que o proxy utiliza internamente.
Python e PHP: as mesmas funcionalidades, a mesma simplicidade
O SDK de Python segue as convenções da biblioteca requests e suporta tanto a utilização síncrona como assíncrona através de asyncio. A inicialização é feita com PCIProxyClient(api_key=os.environ["PCI_PROXY_KEY"]), e todos os métodos aceitam dicionários Python nativos para os parâmetros. A gestão de erros utiliza exceções da hierarquia PCIProxyError, com subclasses para erros de autenticação, validação e de rede.
Para PHP, o pacote Composer instala automaticamente as dependências Guzzle para as chamadas HTTP. O cliente usa interfaces PSR-7 e PSR-18, tornando-o compatível com qualquer framework que siga os padrões PHP-FIG, desde Laravel até Symfony. Os métodos estão documentados com PHPDoc completo e o pacote inclui type stubs para o IDE. Em ambas as linguagens, a transição de sandbox para produção apenas requer alterar a variável de ambiente com a chave de produção.
Perguntas frequentes
O SDK é open source?
O código-fonte do SDK está disponível no GitHub com licença MIT. Qualquer pessoa pode inspecionar a implementação, reportar issues e propor pull requests. O núcleo do vault e da encriptação permanece no servidor da PCI Proxy EU, mas o código cliente que o programador utiliza na sua aplicação é completamente transparente e auditável.
Como gerir os erros de tokenização no SDK?
Cada método do SDK pode lançar exceções tipadas que correspondem a categorias específicas de erro. Os erros de rede e timeout são geridos automaticamente através do mecanismo de retry. Os erros semânticos como cartão inválido ou token expirado são propagados com códigos e mensagens padronizadas que permitem devolver ao cliente uma mensagem adequada sem expor detalhes técnicos internos.
O SDK suporta a detokenização para débitos recorrentes?
O método de detokenização foi concebido especificamente para pagamentos recorrentes e subscrições. O token é criado uma vez durante o primeiro pagamento ou durante a fase de registo do cartão, e depois reutilizado para cada débito posterior sem que o cliente necessite de reintroduzir os dados. O token não tem validade por defeito, mas pode ser configurado com uma data de validade explícita para respeitar as políticas da empresa.
Pronto para integrar o SDK de tokenização na sua stack? Aceda à documentação e ao sandbox e entre em produção em poucos dias. Descubra a 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.