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:
| Scope | Descrição |
|---|---|
customer.write | Concede acesso para criar ou atualizar o registro de um cliente pessoa física. |
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. |
Parâmetros da rota (Path)
No path desta requisição envie o seguinte campo:
| Nome | Tipo | Descrição |
|---|---|---|
documentNumber | path | Obrigató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:
| Nome | Tipo | Descrição | Especificação |
|---|---|---|---|
registerName | string | Obrigatório. Nome conforme consta no documento de identificação (RG, CNH, RNE, DNI ou CRNM) do cliente. | Informe o nome completo, sem abreviações |
socialName | string | Nome pelo qual a pessoa gostaria de ser chamada. Saiba mais consultando a Cartilha do nome social. | — |
birthDate | string | Obrigatório. Data de nascimento do cliente. O cliente deve ter, no mínimo, 18 anos. | Formato YYYY-MM-DD |
phone | object | Obrigatório. Objeto onde devem ser informados os dados do telefone do cliente. | — |
phone.countryCode | string | Obrigatório. Código DDI do país. Atente-se à lista de países bloqueados para Onboarding. | — |
phone.number | string | Obrigatório. Número de telefone (celular) do cliente com DDD (deve ser um número capaz de receber SMS). | — |
address | object | Obrigatório. Objeto onde devem ser informados os dados do endereço do cliente. | — |
address.zipCode | string | Obrigatório. Código postal do endereço. | — |
address.addressLine | string | Obrigatório. Logradouro (Nome da rua, avenida etc.). | Máximo de 256 caracteres. |
address.buildingNumber | string | Obrigatório. Número do imóvel com até dez caracteres. Se não possuir número, substitua por S/N. | — |
address.complement | string | Complemento do endereço. Exemplo: Apto 123, Casa B etc. | — |
address.neighborhood | string | Obrigatório. Nome do bairro ou distrito. | Máximo de 256 caracteres. |
address.city | string | Obrigatório. Nome da cidade. | Máximo de 256 caracteres. Devem-se evitar acentos e outros caracteres especiais. |
address.state | string | Obrigatório. Sigla do estado brasileiro conforme a ISO 3166-2:BR. Exemplo: SP. | — |
address.country | string | Obrigatório. Sigla do país (Brasil) conforme a ISO 3166-2. Exemplo: BR | — |
declaredIncome | string | Obrigató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. | — |
assertedIncome | object | Obrigatório. Objeto que contém dados da renda do cliente. | — |
assertedIncome.value | number | Obrigató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.currency | string | Moeda da renda declarada. O valor padrão é BRL. | — |
occupation | string | Obrigató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. | — |
pep | object | Obrigatório. Objeto onde deve ser informado o nível de exposição política do cliente, atendendo à Circular nº 3.978. | — |
pep.level | string | Obrigató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). | — |
motherName | string | Obrigató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 |
email | string | Obrigatório. Endereço de e-mail. Um mesmo endereço de e-mail não poderá ser usado por dois clientes. | — |
documentation | object | Obrigató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.selfie | string | Obrigatório. Token da análise da selfie. | — |
documentation.idCardFront | string | Obrigatório. Token da análise da frente do documento. | — |
documentation.idCardBack | string | Obrigató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 DDI | País |
|---|---|
| 355 | Albânia |
| 375 | Bielorrússia |
| 387 | Bósnia e Herzegovina |
| 359 | Bulgária |
| 257 | Burundi |
| 850 | Coréia do Norte |
| 385 | Croácia |
| 53 | Cuba |
| 386 | Eslovênia |
| 967 | Iémen |
| 98 | Irã |
| 964 | Iraque |
| 961 | Líbano |
| 218 | Líbia |
| 389 | Macedônia do Norte |
| 382 | Montenegro |
| 236 | República Centro-Africana |
| 242 | República do Congo |
| 243 | República Democrática do Congo |
| 40 | Romênia |
| 7 | Rússia |
| 381 | Sérvia |
| 963 | Síria |
| 252 | Somália |
| 249 | Sudão |
| 211 | Sudão do Sul |
| 58 | Venezuela |
| 263 | Zimbá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 code | Código | Mensagem | Descrição |
|---|---|---|---|
| 409 | CUSTOMER_AWAIT_EVALUATION | Customer await evaluation. | Cliente aguardando análise. |
| 422 | PHONE_ALREADY_IN_USE | Phone already in use to another customer. | O número de telefone já está sendo utilizado por outro cliente. |
| 422 | EMAIL_ALREADY_IN_USE | Email already in use to another customer. | O endereço de e-mail já está sendo utilizado por outro cliente. |
| 422 | INVALID_OCCUPATION | Occupation 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_RECEIVED | A solicitação de cadastro do cliente foi recebida. |
Updated 13 days ago