Uma chave de API de pagamentos funciona como um cartão de dinheiro sem PIN. Quem a enviar pode criar faturas, ler os seus dados de pagamento e, se usar pagamentos a beneficiários, movimentar dinheiro do seu saldo. A segurança da API de pagamentos resume-se, por isso, a três hábitos: manter a chave nos seus próprios servidores, permitir que a API a aceite apenas a partir dos endereços desses servidores e confirmar cada webhook, lendo de volta o pagamento, antes de agir.
Este guia destina-se a responsáveis de engenharia e diretores de pagamentos de PSP (prestadores de serviços de pagamento), IME (instituições de moeda eletrónica), bancos e comerciantes que estão a ligar uma API de pagamento em criptomoedas que liquida em euros. Mostra como restringir uma chave por endereço IP e intervalo CIDR, onde a chave deve ficar, como verificar webhooks e que controlos devem rodear os pagamentos a beneficiários. Os exemplos usam a API e o painel da ItisPay (dados de demonstração).
Momentos-chave
Em resumo
- Uma chave de API é uma credencial ao portador. O GitGuardian contabilizou 28,65 milhões de novos segredos codificados em commits públicos no GitHub em 2025, por isso planeie que uma chave seja divulgada, e não apenas que seja mantida em segurança.
- Uma lista de permissão de IP torna uma chave divulgada inútil fora da sua rede. Inclua os intervalos IPv4 ou IPv6 mais pequenos que cubram os seus endereços de saída reais; uma lista vazia permite todos os endereços.
- Um webhook é uma notificação, não uma prova. Volte a ler a fatura pelo seu ID com a sua chave antes de enviar mercadoria ou creditar uma conta.
- Os pagamentos a beneficiários exigem controlos humanos do seu lado: autenticação em dois passos, IBAN e carteiras de beneficiários guardados e um segundo aprovador acima de um montante definido.
Porque é tão perigosa uma chave de API de pagamentos divulgada?#
Uma chave de API de pagamentos divulgada é perigosa porque a chave é toda a identidade da sua integração. A API da ItisPay, como a maioria das APIs de pagamento, autentica cada pedido com um cabeçalho, Api-key, e a mesma autenticação cobre faturas, pagamentos a beneficiários para um IBAN ou carteira e levantamentos de criptomoedas para um endereço externo. Por isso, a documentação pede que a chave «não fique exposta em código do lado do cliente nem em repositórios públicos».
Na prática, as chaves vazam por locais comuns: código, registos e conversas. Segundo o relatório «State of Secrets Sprawl 2026» da GitGuardian (março de 2026), foram adicionados 28,65 milhões de novos segredos codificados a commits públicos no GitHub em 2025, mais 34 % do que um ano antes. Quando a GitGuardian voltou a testar segredos divulgados em 2022, mais de 64 % ainda eram válidos em janeiro de 2026. As equipas publicam chaves e depois esquecem-se de as substituir.
O OWASP API Security Top 10 (2023) coloca a «Broken Authentication» em segundo lugar e avisa que «o mecanismo de autenticação é um alvo fácil para os atacantes, uma vez que está exposto a todos». O Relatório de Investigações de Violações de Dados de 2025 da Verizon identifica o abuso de credenciais como o vetor de ataque inicial mais comum, com 22 %. Uma cadeia de caracteres secreta, por si só, é uma defesa fraca, por isso o resto deste guia acrescenta camadas que se mantêm mesmo depois de a cadeia ser divulgada.
Como é que uma lista de permissão de IP protege uma chave de API?#
Uma lista de permissão de IP, por vezes chamada lista branca de IP, protege a chave ligando-a a locais e não apenas a uma cadeia de caracteres. A API aceita a chave apenas quando o pedido vem de um endereço que indicou; uma cópia da chave no portátil de um programador, num registo de CI ou num site de partilha de texto não funciona.
No painel da ItisPay, a definição encontra-se em Projects, depois Settings e depois Security, no campo API Allowed IPs. O campo aceita uma lista de endereços individuais e blocos CIDR separados por vírgulas. O texto de ajuda diz: «Deixe vazio para permitir todos os IP. São suportados IPv4 e IPv6.» A mesma lista pode ser definida ao criar um projeto através da API, no campo api_allowed_ips, e uma entrada inválida, como 256.256.256.256, é recusada com um erro de validação em vez de ser guardada.
A predefinição vazia é importante. Um novo projeto aceita a sua chave de qualquer lugar até alguém preencher o campo, por isso coloque esse passo na lista de verificações antes do lançamento, e não na lista de coisas a arrumar mais tarde. Os valores de demonstração na captura de ecrã, 203.0.113.10 e 198.51.100.0/24, pertencem a intervalos que a RFC 5737 reserva para documentação; a sua lista deve conter os seus próprios endereços públicos. Cada projeto tem a sua própria chave de 64 caracteres e a sua própria lista, por isso a produção pode ficar limitada a dois ou três servidores, enquanto um projeto de teste aceita um conjunto mais amplo.
Como escrever intervalos CIDR para IPv4 e IPv6?#
Escreva o intervalo mais pequeno que cubra todos os endereços que os seus servidores realmente usam para chegar à API. A maioria dos problemas com listas de permissão vem de um intervalo demasiado largo ou de um caminho de saída de que alguém se esqueceu.
Como ler um prefixo#
Um bloco CIDR é um endereço seguido de uma barra e de um comprimento de prefixo. A RFC 4632 define o comprimento do prefixo como o número de bits significativos: 192.168.99.0/24 fixa os primeiros 24 bits e deixa 8 livres, o que dá 256 endereços. Cada bit que retira ao prefixo duplica o bloco. Um /32 é um endereço IPv4, um /29 são 8, um /24 são 256 e um /16 são 65 536.
O IPv6 funciona da mesma forma com 128 bits. Um /128 é um endereço. A RFC 4291 fixa a parte de interface da maioria dos endereços IPv6 em 64 bits, por isso a rede de um servidor é normalmente um /64 e o anfitrião pode mudar de endereço dentro dela, por exemplo quando o sistema operativo gera endereços temporários. Se o endereço IPv6 do seu anfitrião mudar e esse /64 for exclusivamente seu, indique o /64 em vez de um único /128. O intervalo de documentação para exemplos IPv6 é 2001:db8::/32 (RFC 3849), por isso nunca o copie para uma lista de permissão real.
Como encontrar o seu endereço de saída real#
O endereço que importa é o que a API vê, e não o que o seu servidor declara sobre si próprio. Atrás de um gateway NAT na nuvem ou de uma firewall corporativa, muitas máquinas partilham um ou dois endereços públicos. As funções sem servidor costumam sair a partir de um conjunto partilhado, a menos que as encaminhe por uma saída fixa. Verifique a partir de cada ambiente, recorrendo a um serviço do tipo «qual é o meu IP», ou leia o endereço de origem nos registos da sua firewall, e depois inclua exatamente esse endereço.
| Configuração | O que listar | Veredicto |
|---|---|---|
| Um servidor com endereço IPv4 público estático | Esse endereço como /32 ou simples | Funciona |
| Vários servidores atrás de um gateway NAT na nuvem | Os endereços públicos do gateway NAT | Funciona |
| Anfitrião IPv6 com endereços que mudam | O /64 do anfitrião, se ninguém mais o usar | Depende |
| Rede do escritório para testes manuais | O endereço fixo do escritório, se o fornecedor o garantir | Depende |
| Funções sem servidor sem saída fixa | Encaminhe-as primeiro por um NAT com endereço estático | Não |
| O intervalo regional completo de um fornecedor de nuvem | Nada; abrange também outros clientes | Não |
Antes de guardar uma alteração, adicione primeiro o novo endereço, implemente, confirme que o tráfego está a fluir e só então remova o antigo. Guardar uma lista que deixa de fora os seus servidores ativos bloqueia o seu próprio checkout.
Onde deve ficar a chave de API e quem a vê?#
A chave deve ficar nos seus servidores, num cofre de segredos, e em nenhum outro lugar. Nunca a inclua numa página do navegador ou numa aplicação móvel, porque qualquer pessoa pode lê-la aí. Também não a coloque em URLs: a OWASP REST Security Cheat Sheet alerta que uma chave num URL pode ser capturada nos registos do servidor web. A sua página de checkout comunica com o seu back end; o back end comunica com a API de pagamento.
Carregue a chave a partir de um gestor de segredos ou de variáveis de ambiente na inicialização, e não de um ficheiro de configuração no repositório. Se aloja código no GitHub, ative a proteção contra envio (push protection): segundo a documentação do GitHub, quando ela «deteta um possível segredo durante uma tentativa de push, bloqueia o push».
Mantenha uma chave por ambiente. Cada projeto da ItisPay tem a sua própria chave e lista de permissões, por isso projetos separados para produção e staging significam que uma chave de staging vazada não pode afetar pagamentos reais. Limite quem pode ver a chave de produção. As orientações de 2019 da Autoridade Bancária Europeia (EBA) sobre segurança de TIC estabelecem a regra de acesso «need-to-know» com «direitos mínimos de acesso», incluindo utilizadores técnicos; desde 2025, o Regulamento DORA (Regulamento sobre Resiliência Operacional Digital) transfere esse dever para a maioria das instituições de pagamento.
Depois, documente como substituiria a chave, antes de precisar. O OWASP Cryptographic Storage Cheat Sheet recomenda renovar as chaves após um período definido e sempre que houver suspeita de comprometimento, e garantir que «o código e os processos necessários para renovar uma chave estejam prontos antes de serem necessários».
Como verificar webhooks de uma API de pagamento?#
Trate um webhook como um aviso de que algo mudou, nunca como prova de que recebeu o pagamento. Qualquer pessoa que descubra o seu URL de callback pode enviar-lhe uma mensagem falsa de «concluído». O padrão seguro é ler a fatura de volta pela API com a sua própria chave e agir com base no que a API devolve.
Ao criar uma fatura na ItisPay, o campo callback_url define o endereço para atualizações de estado. Quando um webhook chega, obtenha o ID da fatura a partir dele, faça um GET à fatura pelo ID e envie ou credite o valor apenas se essa resposta mostrar o estado esperado e o valor que definiu. A documentação descreve este endpoint como devolvendo o estado do pagamento e os detalhes da blockchain «para apresentação aos utilizadores ou verificação».
Algumas regras mantêm o gestor de webhooks limpo:
- Aceite webhooks apenas por HTTPS e rejeite HTTP simples.
- Torne o gestor de webhooks idempotente. Armazene o ID e o estado de cada fatura processada e ignore repetições, pois os fornecedores reenviam avisos.
- Responda rapidamente e execute o trabalho numa fila, para que uma base de dados lenta não desencadeie novas tentativas.
- Se um fornecedor assinar os seus webhooks com HMAC, um hash com chave definido na RFC 2104, recalcule a assinatura e compare-a com uma função de tempo constante. O OWASP Webhook Security Cheat Sheet é direto: «Nunca use ==: isso divulga informação de tempo e pode transformar o endpoint num oráculo de assinatura.» Rejeite mensagens cujo carimbo de data/hora assinado seja antigo demais.
Teste antes do go-live. A ItisPay tem um endpoint que simula uma mudança de estado para uma fatura de teste real e outro que reenvia o último webhook de uma fatura ou ID de encomenda, para que possa verificar novas tentativas e duplicados sem dinheiro real.
Como proteger os pagamentos a beneficiários e o acesso ao painel?#
Os pagamentos a beneficiários são o ponto em que uma chave roubada se transforma em dinheiro perdido, por isso adicione controlos humanos em torno deles. Pelo endpoint de pagamentos a beneficiários da ItisPay, um pagamento em moeda fiduciária vai para um IBAN do beneficiário e um pagamento em cripto vai para um endereço de carteira, ambos a partir do seu saldo disponível. A API faz o que o pedido diz; decidir se um pedido é legítimo é da sua responsabilidade.
Controlos que funcionam do seu lado:
- Autenticação em dois passos para todos com acesso ao painel ou a pagamentos. A legislação de pagamentos da UE já usa esta ideia para utilizadores de serviços de pagamento: as regras da PSD2 sobre autenticação forte do cliente exigem pelo menos dois elementos independentes de entre conhecimento, posse e inerência. Aplique o mesmo padrão à sua própria equipa.
- Beneficiários guardados. Mantenha a sua própria lista de IBAN e endereços de carteira aprovados, e permita que o seu serviço de pagamentos envie apenas para entradas dessa lista. Um novo beneficiário passa por uma aprovação separada, idealmente com um período de carência.
- Um segundo aprovador acima de um limite. Uma pessoa prepara, outra aprova. Defina o valor de acordo com o seu próprio apetite ao risco.
- Um serviço separado de pagamentos a beneficiários. Execute os pagamentos a beneficiários a partir de um único serviço, com o seu próprio endereço fixo na lista de permissões, separado dos servidores de checkout que criam faturas.
| Controlo | O que bloqueia | Veredicto |
|---|---|---|
| Lista de IPs permitidos associada à chave | Utilização de uma chave divulgada a partir do exterior da sua rede | Funciona |
| Chave apenas no servidor | Roubo da chave a partir de navegadores, aplicações e repositórios | Funciona |
| Nova leitura da fatura após um webhook | Notificações falsas de «pago» | Funciona |
| Beneficiários guardados e segundo aprovador | Pagamentos para o IBAN ou a carteira de um atacante | Funciona |
| Qualquer um destes isoladamente contra um servidor comprometido incluído na lista | Roubo por alguém que já está dentro | Não |
O que esperam o DORA e o PCI DSS em relação ao acesso por API?#
Se é uma entidade financeira regulada na UE, estes controlos não são extras opcionais. O Regulamento sobre a Resiliência Operacional Digital (DORA, Regulamento (UE) 2022/2554) é aplicável desde 17 de janeiro de 2025, segundo a EBA. O seu artigo 9.º exige que as entidades «estabeleçam políticas que limitem o acesso físico ou lógico» aos ativos de TIC e que «estabeleçam políticas e protocolos para mecanismos de autenticação forte». Uma chave utilizável apenas no servidor, com lista de IPs permitidos e um plano de rotação, é o tipo de prova que um auditor pede para ver.
O PCI DSS abrange dados de cartões, não faturas de criptoativos. Se a mesma equipa também gerir pagamentos com cartão, o requisito 8.4.2 exige autenticação multifator em todos os acessos ao ambiente de dados do titular do cartão, e os requisitos com prazo diferido da versão 4.0 tornaram-se obrigatórios a 31 de março de 2025.
Onde deixam de funcionar os controlos de segurança das APIs de pagamento?#
Estes controlos restringem as formas de entrada. Por si só, não tornam uma integração segura. Mesmo para quem envia webhooks, a folha de referência da OWASP sobre webhooks classifica a lista de IPs permitidos como «apenas uma camada extra», porque «um IP de saída partilhado não é prova de identidade».
Onde não ajuda
- Um servidor comprometido na lista de IPs permitidos. O atacante envia pedidos a partir de um endereço de confiança com a chave real.
- Endereços de saída partilhados. Se outros clientes saírem da nuvem através do mesmo endereço NAT, a lista não os consegue distinguir de si.
- Uma palavra-passe do painel roubada sem autenticação em dois passos. O atacante contorna a API por completo.
- Dados pessoais em campos da fatura. O endpoint público de faturas da ItisPay devolve todos os detalhes das faturas em aberto sem chave, por isso mantenha os nomes e emails dos clientes fora do nome da encomenda.
Como começar uma integração segura numa tarde?#
Pode concluir a parte técnica de uma integração segura numa tarde, se seguir uma ordem fixa. Os passos abaixo usam a ItisPay; a mesma ordem funciona com qualquer fornecedor.
- Crie um projeto de teste e um projeto de produção separado, cada um com a sua própria chave.
- Guarde as duas chaves no seu gestor de segredos e carregue-as apenas no servidor.
- Encontre o endereço público de saída de cada ambiente e introduza-o em API Allowed IPs.
- Crie uma fatura a partir do back end: faça POST para https://api.itispay.com/api/v1/invoices com o cabeçalho Api-key, um order_id único, fiat_amount com fiat_currency EUR, a moeda em currency e o seu callback_url.
- Crie o gestor de webhooks: apenas HTTPS, idempotente, e volte a ler a fatura pelo ID antes de qualquer ação.
- Execute a simulação de webhook para cada estado que trate e, depois, o endpoint de reenvio para testar duplicados.
- Ative os pagamentos a beneficiários por último, com beneficiários guardados e um segundo aprovador.
Para um arranque rápido, o assistente Ask AI do painel escreve, mediante pedido, código de exemplo, como uma chamada de criação de fatura em Node.js com o cabeçalho Api-key já incluído. Trate-o como um rascunho: confirme os nomes dos campos na referência da API antes de publicar, porque a referência, e não um exemplo gerado, é o contrato. A ItisPay publica também um cliente TypeScript oficial no npm, @itispay/typescript-client.
Se estiver a integrar isto numa configuração mais abrangente de orquestração de pagamentos, atribua a cada fornecedor a sua própria chave, lista de IPs permitidos e gestor de webhooks. O mesmo registo, lido novamente pelo ID, alimenta também a conciliação de pagamentos em criptoativos para a sua equipa financeira.
Se quer aceitar pagamentos em stablecoins e receber em euros sem construir a infraestrutura por si próprio, a ItisPay disponibiliza a API, a faturação, os webhooks e a conciliação, bem como a primeira camada de segurança das APIs de pagamento: chaves que pode restringir aos seus próprios endereços IP. O licenciamento, o KYC e a liquidação para o seu IBAN são executados pelo nosso parceiro licenciado na UE, um prestador de serviços de criptoativos (CASP) e instituição de pagamento, e a maioria das equipas passa do KYB à primeira transação em menos de uma semana.
Este artigo destina-se apenas a fins informativos e não constitui aconselhamento jurídico nem regulamentar.
