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:
Tipo | Exemplo |
---|---|
CPF | 47742663023 |
CNPJ | 34183937000161 |
EVP (chave aleatória) | 8363ff58-2856-4tc6-9ae7-4b048b92a475 |
PHONE (telefone) | +5523415162342 |
[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:
Scope | Descrição |
---|---|
pix.entries.create | Concede acesso para registrar uma chave de endereçamento. |
Cabeçalhos (Headers)
Nome | Descrição |
---|---|
api-version | Obrigatório. Versão da API. Atualmente estamos na versão 1.0. |
Authorization | Obrigatório. Token de autorização do tipo Bearer. |
x-bkly-transactional-hash | Hash gerado na validação TOTP (obrigatório para cadastro de chaves do tipo e-mail e telefone). |
x-correlation-id | Se 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:
Nome | Tipo | Descrição | Especificação |
---|---|---|---|
addressingKey | object | Obrigatório. Objeto que contém informações sobre a chave de endereçamento. | — |
addressingKey.type | string | Obrigatório. Tipo de chave, o qual pode ser: CPF, CNPJ, EVP, PHONE e 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 contém informações sobre a conta à qual a chave Pix será vinculada. | — |
account.branch | string | Obrigatório. Número da agência bancária. | — |
account.number | string | Obrigatório. Número da conta. | |
account.type | string | Tipo de conta: "CHECKING" (conta corrente) ou "PAYMENT" (conta de pagamento). | — |
account.bank | object | Obrigatório. Objeto que contém os dados bancários da conta. | — |
account.bank.ispb | string | Obrigató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.code | string | Obrigatório. Código do banco. | — |
account.bank.name | string | Obrigatório. Nome do banco. | — |
Chave de endereçamento
Chave | Instrução de preenchimento |
---|---|
CPF | 11 dígitos, sem formatação. |
CNPJ | 14 dígitos, sem formatação. |
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": "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 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 Bankly. |
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 | INVALID_USER_ID | Ensure 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. |
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. 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.
Updated about 16 hours ago