Cadastrar a conta bancária

Registra a conta para onde o saque sai. A titularidade é conferida contra o documento do cadastro, e divergência recusa.

POSThttps://api.navenaut.com/kyc/bank-account

Autenticação

A sessão do painel autentica esta rota, e ela é lida de forma autoritativa: não há parâmetro em que o chamador aponte para outra conta.

Esta rota não exige escopo nomeado — o que não quer dizer que ela seja aberta: sem a credencial acima ela recusa.

Exige sessão de vendedor. A conta lida e escrita é sempre a da sessão: não há campo em que o chamador escolha outra.

Parâmetros

Cabeçalho

Nome	Tipo	Descrição
`idempotency-key`obrigatório	texto (uuid)	—

Corpo da requisição

application/json.

Campo	Tipo	Descrição
`accountLabel`obrigatório	texto	Nome livre para você reconhecer a conta. Não tem efeito sobre o pagamento.
`bankAccount`obrigatório	objeto	Banco, agência e conta. São esses os dados que o pagamento usa.
`countryCode`	sempre `BR`	—
`documentNumber`obrigatório	texto	O documento do titular, só dígitos. Ele é conferido contra o cadastro.
`documentType`obrigatório	um de: `cpf`, `cnpj`	Se o titular é pessoa física ou jurídica.
`legalName`obrigatório	texto	O nome do titular, como ele consta no documento.
`ownershipTerm`obrigatório	booleano	O aceite do termo de titularidade, quando o cadastro o exige.
`pixKey`obrigatório	texto	A chave PIX do titular. Ela precisa pertencer ao MESMO documento do cadastro.
`pixKeyType`obrigatório	um de: `cpf`, `cnpj`, `email`, `phone`, `random`	Que tipo de chave PIX você está informando.
`transient`obrigatório	objeto	Marque quando a conta é temporária e não deve substituir a que já está registrada.

{
  "accountLabel": "Loja Exemplo",
  "bankAccount": {
    "accountCheck": "exemplo",
    "accountNumber": "exemplo",
    "accountType": "checking",
    "bankCode": "exemplo",
    "branch": "exemplo"
  },
  "countryCode": "BR",
  "documentNumber": "000.000.000-00",
  "documentType": "cpf",
  "legalName": "Loja Exemplo",
  "ownershipTerm": true,
  "pixKey": "exemplo",
  "pixKeyType": "cpf",
  "transient": {
    "address": {
      "city": "exemplo",
      "complement": "exemplo",
      "district": "exemplo",
      "number": "exemplo",
      "postalCode": "exemplo",
      "state": "exemplo",
      "street": "exemplo"
    },
    "birthDate": "2026-01-15",
    "parentName": "exemplo",
    "phone": "+55 11 90000-0000",
    "responsibleCpf": "000.000.000-00"
  }
}

Respostas

200 · sucesso

{
  "status": {
    "kind": "active"
  }
}

400 · requisição inválida

Corrija e reenvie: o documento do titular não confere, os dados bancários não passaram, o rótulo é inválido, falta o aceite do termo de titularidade, ou a chave PIX pertence a outro titular; a chave de tentativa também é obrigatória.

403 · proibido

Confirme a segurança da conta e envie novamente.

409 · conflito

A conta não pode ser cadastrada agora: o tipo de documento do seu cadastro já está travado, a identidade já recebeu aprovação, ou o cadastro ainda não chegou ao ponto de aceitar uma conta bancária. Confira GET /kyc/status.

503 · indisponível

A validação da conta está indisponível no momento; nada foi cadastrado; repita em instantes.

Erros desta rota

Status	Código	Quando	O que fazer
400	`KYC_OWNERSHIP_TERM_REQUIRED`	O aceite do termo de titularidade não veio marcado. Ele é a afirmação de que a conta informada é da própria titularidade do cadastro, e sem ele nada é escrito: o saque não pode sair para conta de terceiro.	Envie o aceite junto do corpo e reenvie. Repetir sem ele devolve sempre o mesmo 400, e nenhuma conta foi cadastrada.
400	`KYC_DOCUMENT_INVALID`	O documento do titular não passou, e `reason` diz o que reprovou. O valor recusado nunca volta na resposta, de propósito: ele é dado do titular, e repeti-lo aqui o publicaria de graça.	Corrija o documento e reenvie. Confira também `documentType`, porque documento de pessoa física enviado como jurídica reprova pelo tamanho antes de reprovar pelo conteúdo. Nada foi cadastrado.
400	`KYC_BANK_ACCOUNT_INVALID`	Os dados bancários ou a chave PIX não formam uma conta possível, e `reason` diz qual campo reprovou. É recusa de FORMA: nada foi consultado sobre a conta ainda.	Confira banco, agência, conta e a chave PIX contra o que o seu banco mostra, e reenvie. Repetir sem corrigir devolve o mesmo 400.
400	`KYC_PIX_KEY_HOLDER_MISMATCH`	A chave PIX é válida e pertence a OUTRA pessoa que não o titular do cadastro, ou é o CPF ou CNPJ de outro registro informado como telefone ou chave aleatória. Não é erro de digitação da chave: ela existe, e o dono dela não é você.	Informe uma chave do mesmo titular do cadastro, ou corrija o tipo documental se foi ele que ficou errado. Repetir com a mesma chave devolve sempre o mesmo 400.
400	`KYC_ACCOUNT_LABEL_INVALID`	O rótulo livre da conta não passou: veio vazio, só com espaço, ou longo demais. Ele não tem efeito nenhum sobre o pagamento, e ainda assim reprova a escrita inteira, porque escrever a conta com um rótulo que você não pediu seria pior.	Mande um rótulo com texto e reenvie. Nada foi cadastrado.
409	`KYC_DOCUMENT_TYPE_LOCKED`	O cadastro já tem uma conta bancária registrada sob um tipo documental, e este envio traz outro. Trocar pessoa física por jurídica com conta de pé mudaria o titular do destino do saque sem que ninguém tivesse decidido isso.	Remova a conta atual antes de recadastrar sob o outro tipo, ou reenvie mantendo o tipo que já está gravado. Repetir sem uma das duas coisas devolve o mesmo 409.
409	`KYC_NO_ACQUIRER_MAPPED`	Esta conta ainda não tem para onde a validação da conta bancária ser encaminhada. É configuração do nosso lado, não do seu: nada no que você enviou causou isso.	Reporte a ocorrência a quem opera a instalação. Repetir a chamada não muda o resultado, porque não há nada no corpo que resolva.
409	`KYC_ACCOUNT_CREATION_REFUSED`	A criação da conta foi recusada em definitivo por quem valida, e a recusa é sobre ESTA tentativa. O cadastro e a conta que você enviou FORAM gravados assim mesmo: é contra eles que o outro caminho confere o titular depois, e jogá-los fora obrigaria você a digitar tudo de novo.	Siga pelo passo que a resposta indica em `nextStep`, que é a autorização da conta por `POST /kyc/bank-account/authorization`. Reenviar este mesmo cadastro devolve a mesma recusa.
503	`KYC_ACQUIRER_UNAVAILABLE`	A validação da conta não respondeu. Não é recusa: nada foi aprendido sobre a conta, e por isso nada foi gravado, porque uma linha escrita aqui fingiria um progresso que não houve.	Repita em instantes com o mesmo corpo. Diferente da recusa definitiva, aqui repetir é o conserto.
400	`KYC_IDEMPOTENCY_KEY_REQUIRED`	Falta `Idempotency-Key`.	Envie UUID e reutilize nos retries; após nova confirmação, use outro.
400	`KYC_IDEMPOTENCY_KEY_INVALID`	UUID inválido ou chave rotacionada.	Não reutilize; confira o estado e inicie nova tentativa.
403	`ACCOUNT_SECURITY_KYC_CLEARANCE_REQUIRED`	Confirmação recente ausente ou expirada; nenhuma chamada externa ocorreu.	Confirme novamente e gere outra chave.
409	`KYC_IDENTITY_LOCKED`	Identidade já aprovada, mesmo se depois reprovada.	Correção exige fluxo operacional próprio.
409	`KYC_IDEMPOTENCY_KEY_REUSED`	Chave vinculada a conteúdo diferente.	Use chave nova somente em tentativa nova.
409	`KYC_IDEMPOTENCY_KEY_ROTATED`	Chave antiga não valida o conteúdo da repetição.	Peça reconciliação antes de nova tentativa.
409	`KYC_SELLER_SUBMISSION_BUSY`	Outra submissão está ativa.	Aguarde e reutilize a chave atual.
409	`KYC_SUBMISSION_IN_PROGRESS`	Resultado da reserva ainda indefinido.	Repita a mesma chave; não há reenvio automático.
409	`KYC_SUBMISSION_RELEASED`	O envio anterior ficou preso e foi liberado (após 30 minutos ou por um operador).	Descarte a chave e envie o cadastro de novo com uma chave nova.

Os códigos são estáveis e fazem parte do contrato. A lista completa, com todos os vocabulários, está na tabela de erros.

Próximo passo

Autorizar a conta