Registro de pessoa física

stable

Este endpoint permite realizar o registro de clientes do tipo pessoa física.

Pré-requisitos

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

  • A selfie e as fotos (frente e verso) do documento tenham sido enviadas para análise por meio do endpoint Envio e análise de documentos pessoais;
  • A selfie e as fotos (frente e verso) do documento tenham sido aprovadas.

Requisição

Requisição HTTP

PUT https://api-mtls.sandbox.bankly.com.br/customers/{documentNumber}
curl --request PUT \
--url 'https://api-mtls.sandbox.bankly.com.br/customers/47742663023' \
--header 'api-version: 1' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "registerName": "Nísia Floresta",
    "socialName": "Nísia Floresta",
    "birthDate": "1810-10-12",
    "phone": {
        "countryCode": "55",
        "number": "23415162342"
    },
    "address": {
        "zipcode": "68060100",
        "addressLine": "Rua 6 de Março",
        "buildingNumber": "2500",
        "neighborhood": "Alter do Chão",
        "country": "BR",
        "state": "PA",
        "city": "Santarém",
        "complement": ""
    },
    "declaredIncome": "LESS_THAN_ONE_THOUSAND",
    "assertedIncome": {
        "currency": "BRL",
        "value": 500000
  	},
    "occupation": "OCP0082",
    "pep": {
        "level": "NONE" 
    },
    "motherName": "Dionísia Gonçalves Pinto",
    "email": "[email protected]",
    "documentation": {
        "selfie": "ce1849509a3f4625867ead5768d5b068",
        "idCardFront": "9c1974193d96446e84833742aed1db62",
        "idCardBack": "71bb6d35ee7644fe8ef2b8e81eb19f98"
    }
}'

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
customer.writeConcede acesso para criar ou atualizar o registro de um cliente pessoa física.

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.

Parâmetros da rota (Path)

No path desta requisição envie o seguinte campo:

NomeTipoDescrição
documentNumberpathObrigatório. Número do documento CPF do cliente. Informe somente números.

Corpo da requisição (Body)

No body, envie os seguintes campos em formato JSON:

NomeTipoDescriçãoEspecificação
registerNamestringObrigatório. Nome conforme consta no documento de identificação (RG, CNH, RNE, DNI ou CRNM) do cliente.Informe o nome completo, sem abreviações
socialNamestringNome pelo qual a pessoa gostaria de ser chamada. Saiba mais consultando a Cartilha do nome social.---
birthDatestringObrigatório. Data de nascimento do cliente. O cliente deve ter, no mínimo, 18 anos.Formato YYYY-MM-DD
phoneobjectObrigatório. Objeto onde devem ser informados os dados do telefone do cliente.---
phone.countryCodestringObrigatório. Código DDI do país. Atente-se à lista de países bloqueados para Onboarding.---
phone.numberstringObrigatório. Número de telefone (celular) do cliente com DDD (deve ser um número capaz de receber SMS).---
addressobjectObrigatório. Objeto onde devem ser informados os dados do endereço do cliente.---
address.zipCodestringObrigatório. Código postal do endereço.---
address.addressLinestringObrigatório. Logradouro (Nome da rua, avenida etc.).Máximo de 256 caracteres.
address.buildingNumberstringObrigatório. Número do imóvel com até dez caracteres. Se não possuir número, substitua por S/N.---
address.complementstringComplemento do endereço. Exemplo: Apto 123, Casa B etc.---
address.neighborhoodstringObrigatório. Nome do bairro ou distrito.Máximo de 256 caracteres.
address.citystringObrigatório. Nome da cidade.Máximo de 256 caracteres. Devem-se evitar acentos e outros caracteres especiais.
address.statestringObrigatório. Sigla do estado brasileiro conforme a ISO 3166-2:BR. Exemplo: SP.---
address.countrystringObrigatório. Sigla do país (Brasil) conforme a ISO 3166-2. Exemplo: BR---
declaredIncomestringObrigatório. Faixa de renda declarada pelo cliente. Importante: campo obsoleto em produção a partir do dia 27/11/2023. Deve ser substituído pelo objeto assertedIncome.---
assertedIncomeobjectObrigatório. Objeto que contém dados da renda do cliente.---
assertedIncome.valuenumberObrigatório. Valor em Reais da renda declarada pelo cliente.O valor mínimo para esse campo é de: 0.00, e o valor máximo: 99999999999999.99 (até 14 caracteres antes do ponto e até dois caracteres após o ponto).
assertedIncome.currencystringMoeda da renda declarada. O valor padrão é BRL.---
occupationstringObrigatório. Código de ocupação do cliente. Para conhecer a descrição dos códigos das ocupações, consulte a documentação Código de ocupação do cliente. Observação: caso o cliente possua mais de uma ocupação, esse campo deve ser preenchido com a sua principal fonte de renda.---
pepobjectObrigatório. Objeto onde deve ser informado o nível de exposição política do cliente, atendendo à Circular nº 3.978.---
pep.levelstringObrigatório. Nível de exposição política do cliente: "NONE" (o cliente não é e nem tem vínculo com pessoa exposta politicamente), "SELF"(o cliente é pessoa exposta politicamente) e "RELATED" (o cliente tem vínculo familiar, possui sociedade ou é estreito colaborador de pessoa exposta politicamente).---
motherNamestringObrigatório. Nome da mãe do cliente como consta no documento de identidade. Também é possível incluir o nome que consta no campo "Filiação" dos documentos de identificação.Informe o nome completo, sem abreviações
emailstringObrigatório. Endereço de e-mail. Um mesmo endereço de e-mail não poderá ser usado por dois clientes.---
documentationobjectObrigatório. Objeto onde devem ser informadas as referências dos documentos do cliente que foram enviados para análise. Essas referências são retornadas no endpoint de Envio e análise de documentos pessoais.---
documentation.selfiestringObrigatório. Token da análise da selfie.---
documentation.idCardFrontstringObrigatório. Token da análise da frente do documento.---
documentation.idCardBackstringObrigatório. Token da análise do verso do documento.---
{
  "registerName": "Nísia Floresta",
  "socialName": "Nísia Floresta",
  "birthDate": "1810-10-12",
  "phone": {
    "countryCode": "55",
    "number": "23415162342"
  },
  "address": {
    "zipcode": "68060100",
    "addressLine": "Rua 6 de Março",
    "buildingNumber": "2500",
    "neighborhood": "Alter do Chão",
    "country": "BR",
    "state": "PA",
    "city": "Santarém",
    "complement": ""
  },
  "declaredIncome": "LESS_THAN_ONE_THOUSAND",
  "assertedIncome": {
    "currency": "BRL",
    "value": 500000
  },
  "occupation": "OCP0082",
  "pep": {
    "level": "NONE" 
  },
  "motherName": "Dionísia Gonçalves Pinto",
  "email": "[email protected]",
  "documentation": {
    "selfie": "ce1849509a3f4625867ead5768d5b068",
    "idCardFront": "9c1974193d96446e84833742aed1db62",
    "idCardBack": "71bb6d35ee7644fe8ef2b8e81eb19f98"
  }
}

Países bloqueados para Onboarding

Reafirmando o compromisso do Bankly com a segurança, prevenção à lavagem de dinheiro e combate ao terrorismo, vetamos o registro de clientes cujos DDIs sejam provenientes dos países listados a seguir. Clique na seta para expandir a lista:

Países bloqueados
Código DDIPaís
355Albânia
375Bielorrússia
387Bósnia e Herzegovina
359Bulgária
257Burundi
850Coréia do Norte
385Croácia
53Cuba
386Eslovênia
967Iémen
98Irã
964Iraque
961Líbano
218Líbia
389Macedônia do Norte
382Montenegro
236República Centro-Africana
242República do Congo
243República Democrática do Congo
40Romênia
7Rússia
381Sérvia
963Síria
252Somália
249Sudão
211Sudão do Sul
58Venezuela
263Zimbábue

(Fonte: dados agrupados com base nas listas do Conselho Nacional das Nações Unidas - CSNU e do Office of Foreign Assets Control - OFAC)

Resposta (Response)

O status code 202 indicará que o registro do cliente foi realizado com sucesso.

Análise do registro é feita de maneira automática e pode levar até cinco minutos para ser concluída. Ao final desse processo, conheceremos o perfil do cliente e, se ele for aprovado, estará apto para ter uma conta de pagamentos Bankly.

👍

Dica

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

Retorno em caso de reprovação

Se o registro do cliente for reprovado, será preciso realizar uma análise mais detalhada. Quando isso ocorrer, o parceiro poderá solicitar essa análise através do Service Desk do Bankly, o que poderá levar até sete dias úteis para conclusão.

O parceiro e o cliente devem aguardar o resultado dessa análise antes de tentar novamente. Veja quais podem ser os motivos de reprovação de uma análise.

É possível simular uma reprovação de registro, somente em ambiente sandbox, ao utilizar um dos seguintes documentos:

  • 312.806.468-70
  • 101.614.018-56
  • 145.774.718-92
  • 270.205.260-63
  • 102.078.370-23
  • 606.733.970-68

Erros

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

Status codeCódigoDescrição
422PHONE_ALREADY_IN_USEO número de telefone já está sendo utilizado por outro cliente.
422EMAIL_ALREADY_IN_USEO endereço de e-mail já está sendo utilizado por outro cliente.

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

Eventos

Caso o parceiro deseje receber mensagens referentes aos eventos relacionados a esse endpoint, é preciso configurar o webhook. O evento é:

Nome do evento (name)Descrição
CUSTOMER_WAS_RECEIVEDA solicitação de cadastro do cliente foi recebida.