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
Chave Aleatória (EVP)123e4567-e89b-12d3-a456-426655440008
Telefone+5523415162342
E-mail[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é-requisito

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

GET https://api-mtls.sandbox.bankly.com.br/pix/entries
--location --request POST 'https://api-mtls.sandbox.bankly.com.br/pix/entries' \ 
--header 'Accept: application/json' \ 
--header 'Content-Type: application/json' \ 
--header 'api-version: 1.0' \ 
--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ção
addressingKeyobjectObrigatório. Objeto que contém os dados da chave Pix a ser cadastrada.
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.
accountobjectObrigatório. Objeto que contém os dados da 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.typestringObrigatório. Tipo de conta: "CHECKING", para conta corrente, e "PAYMENT", para conta de pagamento.
account.bankobjectObrigatório. Objeto que contém os dados bancários da conta.
account.bank.ispbstringObrigatório. ISPB do banco.
account.bank.codestringObrigatório. Código do banco.
account.bank.namestringObrigatório. Nome do banco.

🚧

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.

{ 
    "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" 
    } 
}

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ódigoDescrição
400INVALID_PARAMETERO valor informado para a chave não corresponde ao tipo de chave informado.
422ADDRESSING_KEY_VALUE_AND_ACCOUNT_HOLDER_DOCUMENT_ARE_DIFFERENTQuando 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_TYPEO tipo de chave de endereçamento não é válido para esse tipo de conta.
422TARGET_ACCOUNT_DOES_NOT_EXISTA chave CPF/CNPJ informada é referente a uma conta não existente.
422INVALID_ACCOUNT_STATUSA chave de endereçamento só pode ser associada a contas com status ACTIVE.
422INVALID_ACCOUNT_HOLDER_STATUSA chave de endereçamento só pode ser associada a clientes com seu registro em status APPROVED.
422MAXIMUM_ENTRIES_COUNT_REGISTERED_FOR_ACCOUNTA conta atingiu o número máximo de registro de chaves de endereçamento.
422ENTRY_ALREADY_EXISTS_TO_SAME_HOLDER_AND_ANOTHER_ACCOUNTEssa 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_HOLDEREssa chave de endereçamento está associada a outro cliente. Considere fazer a reivindicação da chave.
422ENTRY_ALREADY_EXISTS_TO_SAME_ACCOUNTChave de endereçamento já cadastrada para essa conta.
422ENTRY_ALREADY_EXISTS_TO_SAME_OWNER_INTO_ANOTHER_PLAYEREssa 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_INTERVALPara cadastrar mais de uma chave do tipo EVP, é necessário um intervalo de, aproximadamente, um minuto.
422INVALID_USER_IDUser id inválido. Valide se o header x-bkly-pix-user-id é um CPF ou CNPJ válido.
422PERMISSION_NOT_GRANTEDPermissão não concedida para realizar a operação.
422INVALID_PHONE_NUMBER_TO_ADDRESSING_KEYNúmero de telefone não está valido para ser usado como chave de endereçamento.

Válido lembrar que a API também poderá retornar erros comuns entre todos os endpoints.

Eventos

Este endpoint não possui eventos relacionados a ele.