Cadastro de chaves

Este endpoint possibilita realizar o cadastro de chaves do tipo CPF, CNPJ, chave aleatória (EVP), telefone e e-mail.

A seguir, o formato de cada tipo de chave:

Tipo	Exemplo
CPF	47742663023
CNPJ	34183937000161
EVP (chave aleatória)	8363ff58-2856-4tc6-9ae7-4b048b92a475
PHONE (telefone)	+5523415162342
EMAIL	[email protected]

📘
Nota
Lembrando que a pessoa física pode cadastrar até cinco chaves para cada conta transacional. Já a pessoa jurídica pode registrar até 20 chaves.

Pré-requisitos

Para que seja possível utilizar este endpoint, é necessário que:

O cliente possua uma conta ativa;
A chave a ser cadastrada não esteja em uso nesta ou em outra instituição financeira.

Requisição (Request)

Requisição HTTP

POST https://sandbox.hiperbanco.com.br/pix/register-pix-key

--request POST 'https://stageapi.meuacessobackoffice.com.br/pix/register-pix-key' \
--header 'version: cutting-edge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data-raw '{
  "addressingKey": {
    "type": "CPF",
    "value": "39182944717"
  },
  "account": {
    "branch": "0001",
    "number": "1104714229",
    "type": "CHECKING"
  }
}'

Cabeçalhos (Headers)

Nome	Propriedade	Descrição
version	cutting-edge	Essa propriedade garante que o response da API seja retornado no formato JSON

⚠️
Importante
Para solicitação de cadastro de chaves do tipo e-mail e telefone, obrigatoriamente o parceiro precisa gerar o código para validação via TOTP antes da solicitação do cadastro.

Parâmetros da rota (Path)

Não é necessário enviar parâmetros no path desta requisição.

Corpo da requisição (Body)

No body, envie os seguintes campos em formato JSON:

Nome	Tipo	Descrição	Especificação
addressingKey	object	Obrigatório. Objeto que deverá conter informações sobre a chave de endereçamento.
addressingKey.type	string	Obrigatório. Tipo de chave, que pode ser "CPF", "CNPJ", "EVP", "PHONE" ou "EMAIL".
addressingKey.value	string	Obrigatório. Valor da chave a ser criada. Importante: esse campo não deve ser enviado em caso de cadastro de chave do tipo EVP.	Consulte a tabela Chave de endereçamento para obter instruções de preenchimento deste campo.
account	object	Obrigatório. Objeto que deverá conter informações sobre a conta à qual a chave Pix será vinculada.
account.branch	string	Obrigatório. Número da agência.	Padrão: 0001
account.number	string	Obrigatório. Número da conta.
account.type	string	Obrigatório. Tipo de conta, que pode ser "CHECKING" (conta corrente) ou "PAYMENT" (conta de pagamento).	Padrão: PAYMENT
totpCode	string	Enviar código TOTP que chegou por e-mail ou sms Obs.: Esta propriedade deverá ser enviada apenas para os casos de cadastro de chave pix EMAIL e PHONE	Composto por 6 caracteres numéricos (0–9). Apenas números são aceitos; letras e caracteres especiais não são permitidos.

Chave de endereçamento

Chave	Instrução de preenchimento
CPF	11 dígitos, sem caracteres especiais.
CNPJ	14 dígitos, sem caracteres especiais.
EMAIL	Todos os caracteres em minúsculo. Tamanho máximo de 72 caracteres.
PHONE	Número de telefone celular, composto por símbolo ‘+’, seguido pelo código do país, DDD e número de celular com até nove dígitos. Ex.: +5523415162342.

{
  "addressingKey": {
    "type": "CPF",
    "value": "47742663023"
  },
  "account": {
    "type": "CHECKING",
    "branch": "0001",
    "number": "15164"
  }
}

{
  "addressingKey": {
    "type": "CNPJ",
    "value": "12345678900000"
  },
  "account": {
    "type": "CHECKING",
    "branch": "0001",
    "number": "187453"
  }
}

{
  "addressingKey": {
    "type": "EVP"
  },
  "account": {
    "type": "CHECKING",
    "branch": "0001",
    "number": "187453"
  }
}

{
  "addressingKey": {
    "type": "PHONE",
    "value": "+5571981111111"
  },
  "account": {
    "branch": "0001",
    "number": "1104714229",
    "type": "CHECKING"
  },
  "totpCode": "333447"
}

{
  "addressingKey": {
    "type": "EMAIL",
    "value": "[email protected]"
  },
  "account": {
    "branch": "0001",
    "number": "1104714229",
    "type": "CHECKING"
  },
  "totpCode": "312210"
}

⚠️
Importante
Em caso de cadastro de chave do tipo EVP, se o usuário quiser cadastrar mais de uma chave para a mesma conta, é necessário aguardar aproximadamente um minuto para um novo cadastro.

Resposta (Response)

O status code 201 indicará que a chave Pix foi cadastrada com sucesso.

Erros

Este endpoint pode retornar erros específicos, conforme a tabela a seguir:

Status Code	Código	Mensagem	Descrição
422	ADDRESSING_KEY_VALUE_AND_ACCOUNT_HOLDER_DOCUMENT_ARE_DIFFERENT	When addressing key type is CPF or CNPJ the addressing key value must be equal to the account holder document.	Quando o tipo de chave for CPF ou CNPJ, a chave de endereçamento deve ser igual ao documento do detentor da conta no Hiperbanco.
422	ADDRESSING_KEY_TYPE_IS_INVALID_FOR_ACCOUNT_HOLDER_TYPE	Addressing key type is invalid for the Account type.	O tipo de chave de endereçamento não é válido para esse tipo de conta.
422	TARGET_ACCOUNT_DOES_NOT_EXIST	Target account does not exist.	A chave CPF/CNPJ informada é referente a uma conta não existente.
422	INVALID_ACCOUNT_STATUS	Addressing key cannot be linked to account when account status not is ACTIVE.	A chave de endereçamento só pode ser associada a contas com status ACTIVE.
422	INVALID_ACCOUNT_HOLDER_STATUS	Addressing key cannot be linked to account when account holder status not is APPROVED.	A chave de endereçamento só pode ser associada a clientes com seu registro em status APPROVED.
422	MAXIMUM_ENTRIES_COUNT_REGISTERED_FOR_ACCOUNT	Account has reached the maximum entries count registered.	A conta atingiu o número máximo de registro de chaves de endereçamento.
422	ENTRY_ALREADY_EXISTS_TO_SAME_HOLDER_AND_ANOTHER_ACCOUNT	Entry already in use to same holder but to another account. Consider making portability request.	Essa chave de endereçamento já é utilizada por esse cliente, mas em outra conta. Considere fazer uma requisição de portabilidade.
422	ENTRY_ALREADY_EXISTS_TO_ANOTHER_HOLDER	Entry already exists to another holder. Consider making claim request.	Essa chave de endereçamento está associada a outro cliente. Considere fazer a reivindicação da chave.
422	ENTRY_ALREADY_EXISTS_TO_SAME_ACCOUNT	Entry already in use to same account. Consider making change account request.	Chave de endereçamento já cadastrada para essa conta.
422	ENTRY_ALREADY_EXISTS_TO_SAME_OWNER_INTO_ANOTHER_PLAYER	Entry already in use to same owner in another player. Consider making portability request.	Essa chave de endereçamento está sendo utilizada em outra instituição por esse mesmo cliente. Considere fazer uma requisição de portabilidade.
422	EVP_ENTRY_CANNOT_REGISTER_SHORT_INTERVAL	Entry of type EVP cannot be registered in a short interval of time. Please wait a minute and try again.	Para cadastrar mais de uma chave do tipo EVP, é necessário um intervalo de, aproximadamente, um minuto.
422	PERMISSION_NOT_GRANTED	Permission not granted to perform the operation.	Permissão não concedida para realizar a operação.
422	INVALID_PHONE_NUMBER_TO_ADDRESSING_KEY	The phone number must be valid to use it as an addressing key.	Número de telefone não está valido para ser usado como chave de endereçamento.

Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints que acompanham os erros 400 (se houver).

Eventos

Este endpoint não possui eventos relacionados a ele.