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 |
Chave Aleatória (EVP) | 123e4567-e89b-12d3-a456-426655440008 |
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é-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:
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 |
---|---|---|
addressingKey | object | Obrigatório. Objeto que contém os dados da chave Pix a ser cadastrada. |
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. |
account | object | Obrigatório. Objeto que contém os dados da 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 | Obrigatório. Tipo de conta: "CHECKING", para conta corrente, e "PAYMENT", para 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 do banco. |
account.bank.code | string | Obrigatório. Código do banco. |
account.bank.name | string | Obrigató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 code | Código | Descrição |
---|---|---|
400 | INVALID_PARAMETER | O valor informado para a chave não corresponde ao tipo de chave informado. |
422 | ADDRESSING_KEY_VALUE_AND_ACCOUNT_HOLDER_DOCUMENT_ARE_DIFFERENT | 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 | O tipo de chave de endereçamento não é válido para esse tipo de conta. |
422 | TARGET_ACCOUNT_DOES_NOT_EXIST | A chave CPF/CNPJ informada é referente a uma conta não existente. |
422 | INVALID_ACCOUNT_STATUS | A chave de endereçamento só pode ser associada a contas com status ACTIVE. |
422 | INVALID_ACCOUNT_HOLDER_STATUS | A chave de endereçamento só pode ser associada a clientes com seu registro em status APPROVED. |
422 | MAXIMUM_ENTRIES_COUNT_REGISTERED_FOR_ACCOUNT | 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 | 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 | Essa chave de endereçamento está associada a outro cliente. Considere fazer a reivindicação da chave. |
422 | ENTRY_ALREADY_EXISTS_TO_SAME_ACCOUNT | Chave de endereçamento já cadastrada para essa conta. |
422 | ENTRY_ALREADY_EXISTS_TO_SAME_OWNER_INTO_ANOTHER_PLAYER | 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 | Para cadastrar mais de uma chave do tipo EVP, é necessário um intervalo de, aproximadamente, um minuto. |
422 | INVALID_USER_ID | User id inválido. Valide se o header x-bkly-pix-user-id é um CPF ou CNPJ válido. |
422 | PERMISSION_NOT_GRANTED | Permissão não concedida para realizar a operação. |
422 | INVALID_PHONE_NUMBER_TO_ADDRESSING_KEY | Nú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.
Updated about 1 month ago