Recomendações de segurança
O que pedimos de quem integra a API, e o que cada item evita. Nada aqui muda o contrato: o que é opcional continua opcional. O que muda é o quanto a análise de risco consegue ver de cada operação.
Envie o contexto do usuário em toda saída
Quando a chamada sai do seu servidor em nome do cliente, o IP da conexão é o do servidor. Sem mais nada, todas as saídas de todos os seus clientes parecem a mesma origem, e a trava cashoutSourceIps da conta também não tem o que avaliar.
Mande o contexto da pessoa que está do outro lado da tela. Vale para PIX out, TED, boleto, transferência interna e PIX em lote, na credencial de integrador.
Nenhum desses headers é obrigatório e nenhum recusa o pagamento. Valor inválido ou longo demais é descartado e a operação segue. Credencial delegada ignora todos: quem chama é o próprio dono, e o IP da conexão já é o dele.
Dois efeitos, os dois do lado de vocês:
- O cliente legítimo sofre menos bloqueio indevido. O risco passa a ser avaliado por pessoa, não por um servidor que concentra todo mundo.
- Tomada de conta e comportamento fora do padrão são detectados mais cedo pelo nosso antifraude. Se o sistema de vocês for comprometido, o impacto é menor: mesmo com a credencial, quem ataca chega com IP, dispositivo e sessão que não batem com o histórico daquele cliente, e é isso que permite frear a saída antes de a conta ser esvaziada.
Restrinja de onde a credencial chama a API
A allowlist de IP do tenant é o que de fato bloqueia tráfego de origem desconhecida. Não é uma política: ela mora na tela Security do portal (/dashboard/ip-allowlist) ou em PUT /v1/security/ip-allowlist. A escrita exige token de usuário do portal. A credencial M2M não edita a própria allowlist.
Um tenant novo nasce aberto: qualquer IP passa até alguém cadastrar o primeiro. A partir daí, origem fora da lista recebe 403 ip_not_allowed. Os endereços de saída da CorpX (backoffice e internet banking) entram sozinhos, aparecem como sistema e não se removem. Uma lista só com esses endereços vale como lista vazia: o tenant volta a aberto.
Tenant com credencial delegada não edita essa lista na mão (409 ip_allowlist_derived). A allowlist passa a ser por credencial, em GET e PUT /v1/backoffice/tenants/{tenantId}/credentials/{clientId}/ip-allowlist. Adicionar um IP espera 18 horas; remover vale na hora.
Uma credencial por sistema
Peça só os escopos que o sistema usa. Uma credencial que faz PIX out, consulta DICT e abre conta é uma credencial que, vazada, faz as três coisas.
- Não compartilhe o
client_secretentre produção e homologação, nem entre sistemas. - Guarde o segredo em variável de ambiente ou cofre, nunca no código do app do cliente.
- Reuse o token até perto da expiração. Um token por chamada é recusado.
- Na saída de alguém da equipe que tinha o segredo, revogue a credencial e emita outra. Trocar a senha do portal não invalida uma credencial M2M.
Políticas e limites do tenant
As políticas são suas: valor máximo de PIX out, horário de operação, destino bloqueado, limite de consulta de chave. Uma regra que recusa na borda nem chega a debitar. Os limites de valor da conta são o segundo degrau, por operação e por dia.
Sem política, a única barreira de uma saída é o saldo e a análise de risco. Com política, um vazamento de credencial ainda esbarra no teto e no horário que vocês definiram.
Assine o webhook e aceite só a origem certa
Cada evento que enviamos pode ser forjado por quem descobrir a URL. A seção de segurança dos webhooks cobre o que pedimos:
authType: HMACe verificação doX-Signaturesobre os bytes brutos do corpo. Re-serializar o JSON invalida a assinatura.- Liberar no firewall só os IPs de entrega listados nessa página.
- Tratar
eventIdcomo chave de idempotência: a mesma entrega pode chegar mais de uma vez.
Uma chave por pagamento
Reenviar a mesma saída sem Idempotency-Key cria outro pagamento. Gere a chave uma vez, quando a intenção de pagar nasce, e reuse no retry, no timeout e no clique duplo. O identifier do corpo é a chave da operação no seu sistema; os dois juntos é o que a idempotência usa para devolver o resultado original em vez de debitar de novo.
Se suspeitar de fraude
Nesta ordem:
- Revogue a credencial que pode ter vazado e emita outra. Enquanto a antiga vale, quem a tem continua operando.
- Aperte as políticas de saída: horário, valor e destino. Isso vale na hora e não depende de ninguém do outro lado.
- Abra chamado em
suporte@corpx.comcom o horário, a conta e o que vocês já bloquearam.
Do nosso lado, cada saída passa por análise de risco antes de sair, e um PIX recebido em disputa segue o MED.
Checklist
- Toda saída manda
X-Acting-Ipcom o IP do usuário, e o que mais vocês tiverem (X-Acting-Document, user-agent, dispositivo, sessão, geo). - A allowlist de IP do tenant está ativa, com os IPs de vocês e sem sobra de ambiente antigo.
- Cada sistema tem a própria credencial, com o menor escopo que funciona.
- O
client_secretnão está no repositório nem no app do cliente. - PIX out tem teto, horário e limite de consulta de chave.
- O endpoint de webhook valida HMAC no corpo bruto e só aceita os IPs de entrega.
- Cada pagamento nasce com uma
Idempotency-Keyque o retry reusa. - Alguém da equipe sabe revogar a credencial e a quem chamar se suspeitar de fraude.