Cadastro de chaves

stable

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:

TipoExemplo
CPF47742663023
CNPJ34183937000161
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

Requisição HTTP

POST https://api-mtls.sandbox.bankly.com.br/pix/entries
--request POST \
--uri 'https://api-mtls.sandbox.bankly.com.br/pix/entries' \ 
--header 'Accept: application/json' \ 
--header 'Content-Type: application/json' \ 
--header 'api-version: 1.0' \ 
--header 'x-correlation-id: {{GUID}}' \ 
--header 'Authorization: Bearer {{token}}' \ 
--data-raw '{ 
    "addressingKey": { 
        "type": "CPF", 
        "value": "47742663023" 
    }, 
    "account": { 
        "type": "CHECKING", 
        "branch": "0001", 
        "number": "502000027888",
        "bank": {
            "ispb": "13140088",
            "code": "332",
            "name": "Acesso Soluções De Pagamento SA - Instituição de Pagamento"
        }
    }
}'

Autorização

Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.

Esta requisição requer o scope descrito a seguir:

ScopeDescrição
pix.entries.createConcede acesso para registrar uma chave de endereçamento.

Cabeçalhos (Headers)

NomeDescrição
api-versionObrigatório. Versão da API. Atualmente estamos na versão 1.0.
AuthorizationObrigatório. Token de autorização do tipo Bearer.
x-bkly-transactional-hashHash gerado na validação TOTP (obrigatório para cadastro de chaves do tipo e-mail e telefone).
x-correlation-idSe desejar, informe um GUID v4, sendo um novo cada requisição.

🚧

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. O hash gerado nessa etapa deve ser enviado no header x-bkly-transactional-hash.

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:

NomeTipoDescriçãoEspecificação
addressingKeyobjectObrigatório. Objeto que contém informações sobre a chave de endereçamento.
addressingKey.typestringObrigatório. Tipo de chave, o qual pode ser: CPF, CNPJ, EVP, PHONE e EMAIL.
addressingKey.valuestringObrigató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.
accountobjectObrigatório. Objeto que contém informações sobre a conta à qual a chave Pix será vinculada.
account.branchstringObrigatório. Número da agência bancária.
account.numberstringObrigatório. Número da conta.
account.typestringTipo de conta: "CHECKING" (conta corrente) ou "PAYMENT" (conta de pagamento).
account.bankobjectObrigatório. Objeto que contém os dados bancários da conta.
account.bank.ispbstringObrigatório. ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.O campo deve conter oito caracteres. Portanto, se o ISPB do banco contiver apenas seis dígitos, por exemplo, complete-o com zeros à esquerda. Exemplo: "00123456".
account.bank.codestringObrigatório. Código do banco.
account.bank.namestringObrigatório. Nome do banco.

Chave de endereçamento

ChaveInstrução de preenchimento
CPF11 dígitos, sem formatação.
CNPJ14 dígitos, sem formatação.
EMAILTodos os caracteres em minúsculo. Tamanho máximo de 72 caracteres.
PHONENú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": "71911111111" 
    }, 
    "account": { 
        "type": "CHECKING", 
        "branch": "0001", 
        "number": "187453" 
    } 
}
{ 
    "addressingKey": { 
        "type": "EMAIL", 
        "value": "[email protected]" 
    }, 
    "account": { 
        "type": "CHECKING", 
        "branch": "0001", 
        "number": "187453" 
    } 
}

🚧

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.

👍

Dica

Para simular uma requisição nesse endpoint, acesse o API Reference.

Erros

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

Status codeCódigoMensagemDescrição
422ADDRESSING_KEY_VALUE_AND_ACCOUNT_HOLDER_DOCUMENT_ARE_DIFFERENTWhen 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 Bankly.
422ADDRESSING_KEY_TYPE_IS_INVALID_FOR_ACCOUNT_HOLDER_TYPEAddressing key type is invalid for the Account type.O tipo de chave de endereçamento não é válido para esse tipo de conta.
422TARGET_ACCOUNT_DOES_NOT_EXISTTarget account does not exist.A chave CPF/CNPJ informada é referente a uma conta não existente.
422INVALID_ACCOUNT_STATUSAddressing 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.
422INVALID_ACCOUNT_HOLDER_STATUSAddressing 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.
422MAXIMUM_ENTRIES_COUNT_REGISTERED_FOR_ACCOUNTAccount has reached the maximum entries count registered.A conta atingiu o número máximo de registro de chaves de endereçamento.
422ENTRY_ALREADY_EXISTS_TO_SAME_HOLDER_AND_ANOTHER_ACCOUNTEntry 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.
422ENTRY_ALREADY_EXISTS_TO_ANOTHER_HOLDEREntry 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.
422ENTRY_ALREADY_EXISTS_TO_SAME_ACCOUNTEntry already in use to same account. Consider making change account request.Chave de endereçamento já cadastrada para essa conta.
422ENTRY_ALREADY_EXISTS_TO_SAME_OWNER_INTO_ANOTHER_PLAYEREntry 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.
422EVP_ENTRY_CANNOT_REGISTER_SHORT_INTERVALEntry 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.
422INVALID_USER_IDEnsure that the x-bkly-pix-user-id header is a valid CPF or CNPJ document.User id inválido. Valide se o header x-bkly-pix-user-id é um CPF ou CNPJ válido.
422PERMISSION_NOT_GRANTEDPermission not granted to perform the operation.Permissão não concedida para realizar a operação.
422INVALID_PHONE_NUMBER_TO_ADDRESSING_KEYThe 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. Portanto, recomendamos a consulta da documentação de erros, onde é possível encontrar as mensagens comuns em inglês que acompanham os erros 400 (se houver).

Eventos

Este endpoint não possui eventos relacionados a ele.