> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# 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.

| Header                | O que mandar                                                 | Limite         |
| --------------------- | ------------------------------------------------------------ | -------------- |
| `X-Acting-Ip`         | IP real do usuário, não o do seu servidor                    | IPv4 ou IPv6   |
| `X-Acting-Document`   | CPF de quem opera a saída                                    | 11 dígitos     |
| `X-Acting-User-Agent` | User-agent do browser ou do app                              | 512 caracteres |
| `X-Acting-Device-Id`  | Identificador de dispositivo do seu sistema                  | 128 caracteres |
| `X-Acting-Session-Id` | Sessão do usuário no seu sistema                             | 128 caracteres |
| `X-Acting-Geo`        | `latitude,longitude` em graus decimais (`-22.9068,-43.1729`) | faixa válida   |

```bash
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](/baas/guias/autenticacao/oauth2) 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](/baas/guias/autenticacao/politicas) 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](/baas/guias/pagar/limites) 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](/baas/guias/conta/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](/baas/guias/comece-aqui/idempotencia) 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](/baas/guias/autenticacao/politicas) 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](/baas/guias/pagar/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.