Skip to navigation

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.

HeaderO que mandarLimite
X-Acting-IpIP real do usuário, não o do seu servidorIPv4 ou IPv6
X-Acting-DocumentCPF de quem opera a saída11 dígitos
X-Acting-User-AgentUser-agent do browser ou do app512 caracteres
X-Acting-Device-IdIdentificador de dispositivo do seu sistema128 caracteres
X-Acting-Session-IdSessão do usuário no seu sistema128 caracteres
X-Acting-Geolatitude,longitude em graus decimais (-22.9068,-43.1729)faixa válida
curl -X POST "https://tenant.api.corpx.com/v1/accounts/acc-123/pix/payments" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: tenant-suaempresa" \
-H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
-H "X-Acting-Document: 12345678909" \
-H "X-Acting-Ip: 200.10.20.30" \
-H "X-Acting-User-Agent: MeuApp/4.2 (Android 14)" \
-H "X-Acting-Device-Id: dev_8f3a1c" \
-H "X-Acting-Session-Id: sess_19ab" \
-H "X-Acting-Geo: -22.9068,-43.1729" \
-H "Content-Type: application/json" \
-d '{ "pixKey": "cliente@email.com", "amount": "150.00" }'

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_secret entre 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: HMAC e verificação do X-Signature sobre 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 eventId como 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:

  1. Revogue a credencial que pode ter vazado e emita outra. Enquanto a antiga vale, quem a tem continua operando.
  2. 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.
  3. Abra chamado em suporte@corpx.com com 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-Ip com 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_secret nã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-Key que o retry reusa.
  • Alguém da equipe sabe revogar a credencial e a quem chamar se suspeitar de fraude.