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.
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:
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.
Ler
Escrever
PUT recebe o documento inteiro desejado (escopo security_locks.manage):
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.
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:
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
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.
Credencial delegada ignora esses headers: quem chama é o próprio dono, e o IP da conexão já é o dele.
Erros
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
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
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:
Falta de qualquer um dos dois devolve 428 pin_required.
Bloqueio por tentativas
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.
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
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
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
Documentos saem mascarados. lockedUntil: null com requiresReset: true é o bloqueio duro — a saída é redefinir, não esperar.
Erros
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:
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 — o que pedimos de quem integra: contexto do usuário, allowlist de IP, credencial e webhook
- Cashout — as rotas de saída onde as travas e o PIN incidem
- Assinatura de Requisição — o outro lado do desenho: credencial por conta
- Erros — catálogo completo