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 (Request)

Requisição HTTP

PUT https://api-mtls.sandbox.bankly.com.br/customers/{documentNumber}
--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çãoEspecificaçã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. Máximo de 256 caracteres.
socialNamestringNome pelo qual a pessoa gostaria de ser chamada. Saiba mais consultando a Cartilha do nome social.Máximo de 256 caracteres.
birthDatestringObrigatório. Data de nascimento do cliente. O cliente deve ter, no mínimo, 18 anos.Formato YYYY-MM-DD.
phoneobjectObrigatório. Objeto que deverá conter informações sobre o 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 que deverá conter informações sobre o 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.Formato ISO 3166-2:BR.
address.countrystringObrigatório. Sigla do país (Brasil).Formato ISO 3166-2:BR.
assertedIncomeobjectObrigatório. Objeto que deverá conter os 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. 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 que deverá conter informações sobre 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, o qual pode ser "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. Máximo de 256 caracteres.
emailstringObrigatório. Endereço de e-mail.Um mesmo endereço de e-mail não poderá ser usado por dois clientes. Máximo de 256 caracteres.
documentationobjectObrigatório. Objeto que deverá conter informações sobre 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": ""
  },
  "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ódigoMensagemDescrição
409CUSTOMER_AWAIT_EVALUATIONCustomer await evaluation.Cliente aguardando análise.
422PHONE_ALREADY_IN_USEPhone already in use to another customer.O número de telefone já está sendo utilizado por outro cliente.
422EMAIL_ALREADY_IN_USEEmail already in use to another customer.O endereço de e-mail já está sendo utilizado por outro cliente.
422INVALID_OCCUPATIONOccupation provided is invalid.Código de ocupação do cliente inválido.

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

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.