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

# Segurança da Conta

Três controles que o **titular** da conta configura e que a API passa a aplicar em toda tentativa de saída de dinheiro: travas de cashout, PIN transacional e visibilidade de quem tem acesso compartilhado à conta.

Eles existem para o cenário em que a credencial e o token do integrador estão corretos — e é a sessão do correntista que foi tomada. Nada aqui é opt-out por requisição: o que o titular configurou vale mesmo para a credencial que o configurou.

> **Nada muda se você não usar**
>
> Toda conta começa sem trava e sem PIN, e o comportamento é o de hoje. Os controles só passam a valer depois de configurados.

## Travas de cashout

`account security locks` são três limites independentes:

| Campo              | Efeito                                                         |
| ------------------ | -------------------------------------------------------------- |
| `cashoutBlocked`   | `true` recusa **toda** saída da conta                          |
| `cashoutHours`     | Só permite saída dentro da janela (`HH:MM`, 24h, com timezone) |
| `cashoutSourceIps` | Só permite saída de IPs/CIDRs declarados                       |

No P2P Cripto, a conta que anuncia **compra** tem o valor das ordens bloqueado no próprio saldo. Por isso `cashoutBlocked` pausa os anúncios de compra ativos, e fora de `cashoutHours` eles saem do livro até a janela abrir. Veja [Anúncios](/baas/guias/p2p/anuncios).

### Ler

```bash
curl "https://tenant.api.corpx.com/v1/accounts/acc-123/security/locks" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: tenant-suaempresa"
```

```json
{
  "accountId": "acc-123",
  "current": {
    "cashoutBlocked": false,
    "cashoutHours": { "start": "08:00", "end": "18:00", "timezone": "America/Sao_Paulo" },
    "cashoutSourceIps": ["200.10.20.30/32"]
  },
  "updatedAt": "2026-09-19T12:00:00Z"
}
```

### Escrever

`PUT` recebe o documento **inteiro** desejado (escopo `security_locks.manage`):

```bash
curl -X PUT "https://tenant.api.corpx.com/v1/accounts/acc-123/security/locks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "X-Acting-Document: 12345678909" \
  -H "X-Acting-Ip: 200.10.20.30" \
  -H "Content-Type: application/json" \
  -d '{
    "cashoutBlocked": false,
    "cashoutHours": { "start": "08:00", "end": "18:00", "timezone": "America/Sao_Paulo" },
    "cashoutSourceIps": ["200.10.20.30/32"]
  }'
```

### Apertar vale já; afrouxar espera 6 horas

Esta é a parte que muda o seu fluxo, então vale ler com atenção: **a decisão é campo por campo**.

| Mudança                                          | Quando vale |
| ------------------------------------------------ | ----------- |
| Ligar `cashoutBlocked`                           | Imediato    |
| Desligar `cashoutBlocked`                        | **+6h**     |
| Estreitar `cashoutHours`, ou passar a ter janela | Imediato    |
| Ampliar ou remover `cashoutHours`                | **+6h**     |
| Remover IP de `cashoutSourceIps`                 | Imediato    |
| Adicionar IP, ou remover a lista toda            | **+6h**     |

Quem liga o bloqueio e amplia o horário na mesma chamada tem o bloqueio **agora** e o horário **depois**. A resposta diz exatamente isso:

```json
{
  "accountId": "acc-123",
  "current": { "cashoutBlocked": true, "cashoutHours": { "start": "08:00", "end": "18:00" } },
  "pending": { "cashoutBlocked": true, "cashoutHours": { "start": "00:00", "end": "23:59" } },
  "pendingEffectiveAt": "2026-09-19T18:00:00Z",
  "pendingReason": "relaxing_security_requires_grace"
}
```

A assimetria é o desenho inteiro: quem tomou a conta quer **desligar** o bloqueio, ampliar o horário, adicionar o próprio IP — nunca apertar. Uma carência simétrica protegeria o atacante e puniria o titular que está reagindo a uma fraude em andamento.

### Cancelar ou antecipar o afrouxamento

```bash
# Cancelar: descarta o pendente, o current continua valendo. Imediato.
curl -X DELETE ".../v1/accounts/acc-123/security/locks/pending" ...

# Antecipar: promove o pendente agora. EXIGE o PIN do operador.
curl -X POST ".../v1/accounts/acc-123/security/locks/pending/approve" \
  -H "X-Acting-Document: 12345678909" \
  -H "X-Transaction-Pin: 918273" ...
```

Antecipar é o único caminho que encurta a carência, e por isso ele custa a única coisa que quem invadiu a sessão não tem: o PIN. Sem esse endpoint, o titular legítimo que quer liberar o próprio cashout teria de esperar 6h sem alternativa.

### `X-Acting-Ip`

Quando a chamada vem de um servidor seu em nome do correntista (o caso do internet banking), o IP da conexão é o do **seu** servidor, não o do usuário. `cashoutSourceIps` seria inútil. Informe o IP real do usuário em `X-Acting-Ip` — é ele que a trava avalia.

O header só é aceito de credenciais de integrador. Uma credencial delegada é usada direto pelo dono, então o IP da conexão já é o certo e `X-Acting-Ip` é ignorado.

### Contexto do usuário

Além do IP, a credencial de integrador pode mandar o contexto do correntista. Tudo é opcional, alimenta a análise de risco e **nunca bloqueia** o pagamento: valor inválido ou longo demais é descartado e a chamada segue.

| Header                | O que é                                                      | Limite         |
| --------------------- | ------------------------------------------------------------ | -------------- |
| `X-Acting-User-Agent` | User-agent do browser ou app do usuário                      | 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   |

Credencial delegada ignora esses headers: quem chama é o próprio dono, e o IP da conexão já é o dele.

### Erros

| Code                            | HTTP | Quando                                                     |
| ------------------------------- | ---- | ---------------------------------------------------------- |
| `cashout_locked`                | 423  | `cashoutBlocked: true`                                     |
| `cashout_outside_hours`         | 403  | Fora de `cashoutHours`. A mensagem traz a janela           |
| `cashout_source_ip_not_allowed` | 403  | IP de origem fora de `cashoutSourceIps`                    |
| `invalid_cashout_hours`         | 422  | `HH:MM` inválido, `start == end`, ou timezone desconhecido |
| `no_pending_change`             | 404  | `DELETE`/`approve` sem afrouxamento agendado               |

## PIN transacional

O PIN é da **pessoa** (CPF em `X-Acting-Document`) dentro do tenant, não da conta. Duas contas do mesmo CPF compartilham o PIN e o contador de erros. A família nova é `/v1/people/pin` (o CPF vai no header, não no path). As rotas `/v1/accounts/{accountId}/security/pin` continuam funcionando, com o mesmo JSON, e escrevem esse mesmo PIN.

Ele só é exigido quando a credencial do chamador está marcada para isso — na prática, a credencial do internet banking, onde uma única credencial atende muitos correntistas e o token, sozinho, não distingue quem está do outro lado da tela.

### Cadastrar e trocar

```bash
curl -X PUT "https://tenant.api.corpx.com/v1/accounts/acc-123/security/pin" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json" \
  -d '{ "actingDocument": "12345678909", "pin": "918273" }'
```

```json
{ "accountId": "acc-123", "actingDocument": "123.***.***-09", "status": "created" }
```

Trocar um PIN existente exige o atual no mesmo corpo (`currentPin`). Sem isso, quem tomou a sessão trocaria o PIN e o PIN pararia de proteger qualquer coisa.

O escopo é `pin.manage`. O PIN nunca aparece em log ou resposta — é armazenado como hash argon2id e o valor em claro é descartado.

Quando a redefinição pela página da CorpX está habilitada, o `PUT` **sem** `currentPin` de um PIN que já existe responde **403** `pin_change_disabled`. Quem manda o `currentPin` certo troca mesmo com a página ligada. O primeiro cadastro não manda `currentPin`.

### Regras do PIN

| Regra      | Valor                                                                                                                                                                                                      |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tamanho    | 6 a 12 dígitos                                                                                                                                                                                             |
| Só dígitos | Sim                                                                                                                                                                                                        |
| Recusa     | Dígitos todos iguais (`111111`), sequência inclusive com volta (`123456`, `654321`, `890123`), padrão de período curto (`121212`, `123123`) e PIN contido na data de nascimento ou no documento do titular |

PIN recusado devolve **422** `weak_pin` com a razão nomeada.

### Usar

Nas rotas de saída (PIX out, TED, boleto, transferência interna), quando a credencial exige PIN:

```bash
curl -X POST ".../v1/accounts/acc-123/pix/payments" \
  -H "X-Acting-Document: 12345678909" \
  -H "X-Transaction-Pin: 918273" ...
```

Falta de qualquer um dos dois devolve **428** `pin_required`.

### Bloqueio por tentativas

| Tentativas erradas | Efeito                                                                                  |
| ------------------ | --------------------------------------------------------------------------------------- |
| 3                  | Bloqueio de **15 minutos** (**429** `pin_temporarily_locked`, com header `Retry-After`) |
| 6                  | Bloqueio até **redefinição** (**423** `pin_locked`)                                     |

Um PIN correto zera o contador. O `DELETE` não apaga a linha: trava o PIN da pessoa (`423 pin_locked` no cashout) e ela continua cadastrada, então o pedido de redefinição abaixo continua valendo. A página facial também destrava.

```bash
curl -X DELETE "https://tenant.api.corpx.com/v1/people/pin" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: tenant-suaempresa" \
  -H "X-Acting-Document: 12345678909"
```

O alias `DELETE /v1/accounts/{accountId}/security/pin/{document}` faz a mesma trava. Com a página desligada, um `PUT` sem `currentPin` depois desse `DELETE` recadastra — é o reset que o internet banking já faz.

### Redefinir na página da CorpX

```bash
curl -X POST "https://tenant.api.corpx.com/v1/accounts/acc-123/security/pin/reset-request" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json" \
  -d '{ "actingDocument": "52998224725", "displayMessage": "Confirme seu rosto para escolher um PIN novo." }'
```

```json
{
  "resetId": "pinrst_8c1f6a2e-4d3b-4b9a-9f0e-1a2b3c4d5e6f",
  "resetUrl": "https://tenant.api.corpx.com/v1/security/pin-reset#…",
  "expiresAt": "2026-09-27T18:00:00Z"
}
```

O operador abre `resetUrl`, faz a prova facial e, se ela for aprovada, escolhe o PIN novo na mesma página. O integrador não vê e não escolhe o valor — o corpo deste pedido não aceita `pin`. `displayMessage` é texto simples, opcional, e aparece na página do jeito que foi enviado.

A página sai com a marca do tenant: nome, logo e cores configurados para ele, ou o nome cadastrado do tenant quando não há marca. A CorpX aparece só no rodapé. O campo aceita exatamente 6 dígitos, o tamanho que o teclado de PIN do internet banking digita; o `PUT` continua aceitando de 6 a 12.

Exige PIN já cadastrado, inclusive PIN invalidado pelo `DELETE`. Sem PIN, **409** `pin_reset_not_enrolled` e o primeiro cadastro continua no `PUT`. Sem a página habilitada para o tenant, **403** `feature_disabled`. O link vale 30 minutos. O quinto pedido da mesma pessoa na mesma hora responde **429** `pin_reset_rate_limited` — a cota é da pessoa, somada entre as contas e entre o alias. Um pedido novo expira links anteriores ainda abertos. O mesmo pedido existe em `POST /v1/people/pin/reset-request`, com o CPF em `X-Acting-Document`.

### Verificar antes de montar o pagamento

```bash
curl -X POST ".../v1/accounts/acc-123/security/pin/verify" \
  -H "Content-Type: application/json" \
  -d '{ "actingDocument": "12345678909", "pin": "918273" }'
```

Existe para a tela confirmar o PIN **antes** do formulário de pagamento. Sem ele, o usuário descobriria o PIN errado no fim do fluxo — e cada erro queimaria uma das 3 tentativas. Tentativa errada aqui conta igual: o endpoint não é um oráculo grátis.

### Estado dos operadores

```bash
curl ".../v1/accounts/acc-123/security/pin/status" ...
```

```json
{
  "accountId": "acc-123",
  "items": [
    { "actingDocument": "123.***.***-09", "failedAttempts": 0, "locked": false,
      "setAt": "2026-09-19T12:00:00Z", "updatedAt": "2026-09-19T12:00:00Z" },
    { "actingDocument": "987.***.***-21", "failedAttempts": 6, "locked": true,
      "lockedUntil": null, "requiresReset": true,
      "setAt": "2026-09-01T10:00:00Z", "updatedAt": "2026-09-19T14:22:00Z" }
  ],
  "policy": { "minLength": 6, "maxLength": 12, "softLockAfter": 3,
              "softLockMinutes": 15, "hardLockAfter": 6,
              "digitsOnly": true, "rejectsSequential": true }
}
```

Documentos saem mascarados. `lockedUntil: null` com `requiresReset: true` é o bloqueio duro — a saída é redefinir, não esperar.

### Erros

| Code                     | HTTP | Quando                                                      |
| ------------------------ | ---- | ----------------------------------------------------------- |
| `pin_required`           | 428  | Rota de saída sem `X-Acting-Document` / `X-Transaction-Pin` |
| `pin_invalid`            | 403  | PIN errado. A tentativa foi contada                         |
| `pin_not_set`            | 403  | Essa pessoa não tem PIN neste tenant                        |
| `pin_temporarily_locked` | 429  | 3 erros. Aguarde os 15 minutos                              |
| `pin_locked`             | 423  | 6 erros, ou PIN invalidado pelo `DELETE`                    |
| `weak_pin`               | 422  | PIN fora da política                                        |
| `pin_not_found`          | 404  | `DELETE` de uma pessoa sem PIN                              |
| `pin_change_disabled`    | 403  | Troca sem `currentPin` com a página facial ligada           |
| `pin_reset_not_enrolled` | 409  | Pedido de redefinição sem PIN cadastrado                    |
| `pin_reset_rate_limited` | 429  | Mais de cinco pedidos da mesma pessoa na última hora        |

## Acesso compartilhado

Uma mesma conta bancária pode ser acessada por mais de um tenant — o correntista contratou dois sistemas, ou migrou de um para outro e o antigo ainda tem acesso. O titular tem direito de ver isso:

```bash
curl ".../v1/accounts/acc-123/shared-access" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: tenant-suaempresa"
```

```json
{
  "accountId": "acc-123",
  "items": [
    { "tenantId": "tenant-suaempresa", "displayName": "Sua Empresa",
      "status": "active", "since": "2026-01-15T10:00:00Z", "isCurrent": true },
    { "tenantId": "tenant-outro", "displayName": "Outro Integrador",
      "status": "suspended", "since": "2025-08-02T09:30:00Z", "isCurrent": false }
  ]
}
```

Só metadado público: nome de exibição, estado e desde quando. Nada de credencial, volume, saldo ou configuração dos outros tenants. `status` é o do acesso daquele tenant à conta, não o do tenant — uma linha `suspended` aparece justamente para o titular confirmar que a revogação pegou.

Escopo de leitura. Revogar acesso é operação de backoffice, não desta rota.

## Ver também

* [Recomendações de segurança](/baas/guias/autenticacao/recomendacoes-de-seguranca) — o que pedimos de quem integra: contexto do usuário, allowlist de IP, credencial e webhook
* [Cashout](/baas/guias/pagar/pix-out) — as rotas de saída onde as travas e o PIN incidem
* [Assinatura de Requisição](/ib/guias/autenticacao/assinatura-de-requisicoes) — o outro lado do desenho: credencial por conta
* [Erros](/baas/guias/referencia/erros) — catálogo completo