Utilização do KYC Celcoin

Introdução

Utilize esta API para enviar os documentos coletados dos usuários e validá-los através da nossa documentoscopia. Para utilização destes serviços é necessário realizar a contratação do KYC Celcoin junto a solução do BaaS.

Aos usuários que utilizam esta API para inserir relatórios de KYC EXTERNO, as análises serão realizadas pelo nosso time de riscos. Veja mais detalhes sobre isso no último tópico dessa página "Caso não utilize o KYC Celcoin".

Pré requisitos para implementação:

• Possuir uma chave API da Celcoin, essa chave API é enviada após contratar o serviço conosco. link.

• Ter familiaridade com APIs Rest usando o protocolo OAuth 2.0.

• Ter o produto/solução contratada, caso queira usar a funcionalidade em ambiente produtivo, por favor entre em contato com a nossa equipe comercial através do e-mail [email protected]. Para dúvidas técnicas, basta entrar em contato com o suporte através do link.

Fluxo de integração

Enviar documentos

Documentos que devem ser enviados através do endpoint /fileupload:

• Pessoa Física: os documentos obrigatórios que devem ser enviados frente e verso, são RG (contendo o CPF) ou CNH . Apenas documentação original, não aceitamos cópias mesmo que autenticadas.
• Pessoa Jurídica: os documentos obrigatórios são: cópia atualizada do contrato social e faturamento (ou balanço).
  Também será obrigatória a foto frente e verso do RG (contendo o CPF) ou CNH de pelo menos um dos sócios administradores . Apenas documentação original, não aceitamos cópias mesmo que autenticadas.

Tabela de arquivos disponíveis para inserção no campo filetype

Quando realizar os documentos?

Antes da realização do envio dos documentos, é importante já ter realizado o processo de abertura de conta. Após a realização do processo, será enviado um evento sinalizando a pendencia de documentação (você pode acessar os templates de webhooks para mais detalhes).

Exemplo:

{
                        "entity": "kyc",
                        "createTimestamp": "2023-07-26T19:31:14.803Z",
                        "status": "PENDING",
                        "body": {
                            "clientCode": "416bbac2-47b6-4518-8520-a7ae20df0e",
                            "documentNumber": "85467256084",
                            "onboardingId": "eb616474-87f2-442e-9661-6c8734a0e12e"
                        }
                    }

Modelos de request:

O envio de documentos poderá ocorrer das seguintes formas:

🙍‍♂️

Pessoa Física

Se o envio for de um documento de pessoa física:

form-data

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/celcoinkyc/document/v1/fileupload' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
-F'cnpj='//cnpj vazio
-F'documentnumber=66668506020'//numero do CPF
-F'filetype=CNH'//tipo de documento
-F'front=@/path/cnh.jpeg'//foto da cnh aberta

🏛️

Pessoa Jurídica

Neste caso, o envio será tanto dos documentos da empresa (cópia de contrato social, cartão cnpj e balanço (ou faturamento), quanto os documentos de cada sócio dessa empresa ou pelo menos do sócio administrador. Envie as requisições dessa forma:

• Documentos da empresa:

form-data

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/celcoinkyc/document/v1/fileupload' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer {{access_token}}' \
-F'cnpj=22506895000173'//numero do CNPJ
-F'documentnumber=22506895000173'//numero do CNPJ
-F'filetype=CONTRATO_SOCIAL'//tipo de documento
-F'front=@/path/contrato_social.pdf'//arquivo pdf do cartao cnpj

• Documentos dos sócios:

form-data

curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/celcoinkyc/document/v1/fileupload' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer {{access_token}}' \
-F'cnpj=22506895000173'//numero do CNPJ da empresa
-F'documentnumber=21912051001'//numero do CPF do socio
-F'filetype=RG'//tipo de documento
-F'front=@/path/rg_frente.jpeg'//foto da frente do RG do sócio
-F'verse=@/path/rg_verso.jpeg'//foto do verso do RG do sócio

✅

Envie o arquivo de documento sempre como Multipart/Form

Multipart envia arquivos/dados para o servidor no formato de array de bytes. Dados de várias partes/formulários são aplicados a um formulário, portanto, você pode enviar tudo em um formulário, incluindo dados "regulares" também.

⚠ Nunca envie os arquivos em base64 ⚠

🚧

Requisição individual por documento

Se for enviar mais de um documento por pessoa física ou jurídica, envie esses em diferentes requisições.

No caso de empresas que têm mais que um sócio, por exemplo, caso opte por enviar o documento de todos os sócios, será necessário o envio individual do documento de cada sócio.

Entenda com quais informações os campos devem ser preenchidos

• O campo cnpj deverá ser preenchido sempre com um número de CNPJ válido e sem pontos e traços.
• O campo documentnumber pode ser preenchido por um CNPJ ou CPF, mas nunca com outros documentos. Esse campo também deve ser preenchido sem pontos e traços.
• Preencha o campo filetype com maiúsculas, da forma como descrevemos na tabela de arquivos acima.
• No campo front, insira a foto da parte da frente do documento enviado ou, no caso de um documento de face única, utilize este parâmetro para enviar o arquivo.
  Serão aceitos arquivos nos formatos: jpeg , jpg e pdf, mas especificamente para RG e CNH, o formato do arquivo deve ser jpeg ou jpg, os demais tipos de arquivos poderão ser enviados no formato de pdf.
• No campo verse, insira a foto do verso do documento.
  Serão aceitos arquivos nos formatos: jpeg , jpg e pdf, mas especificamente para RG e CNH, o formato do arquivo deve ser jpeg ou jpg, os demais tipos de arquivos poderão ser enviados no formato de pdf.
• Tamanho máximo de arquivo aceito de 12 MB.

❗️

Os envios devem ser realizados após a solicitação de criação de conta

Importante apenas chamar este serviço de inclusão de documentos após já ter realizado a solicitação de criação de conta. Em caso de erro 404, realize uma nova tentativa após no mínimo 30 segundos.

OBS: Recomendável que seja realizado no mínimo 30 segundos após a solicitação de criação de conta.

Modelo de response:

{
"status": 200,
"message":"Arquivo enviado com sucesso"
}

Quando não houver um registro de background check, ou seja, uma solicitação de criação de conta (conforme observação no quadro acima), o response virá da seguinte forma:

{
    "errorCode": 404,
    "errorMessage": "BackgroundCheck nao encontrado!"
}

Estrutura do response:

Eventos de aprovação ou rejeição do KYC

Assim como o evento de pendencia, após as análises (que possuem o SLA de até 48h), enviaremos um evento via webhook, com os seguintes cenários:

Em caso de aprovação:

{
                        "entity": "kyc",
                        "createTimestamp": "2023-07-26T21:13:04.856Z",
                        "status": "APPROVED",
                        "body": {
                            "clientCode": "416bbac2-47b6-4518-8520-a487aedf0e",
                            "documentNumber": "85467256084",
                            "onboardingId": "eb616474-87f2-442e-9661-6c8734a0e12e"
                        }
                    }

Em caso de negativa:

{
                        "entity": "kyc",
                        "createTimestamp": "2023-07-26T15:18:36.210Z",
                        "status": "REJECTED",
                        "body": {
                            "clientCode": "b16e3672-d047-46fa-ad70-ec0c4bf3bf",
                            "documentNumber": "85467256084",
                            "onboardingId": "03c2b4e0-6e2c-49e5-ac9b-753d33d5d9df"
                        }
                    }

Em caso de pendenciamento: (Casos de pendenciamento ocorrem quando faltou alguma documentação para a análise do KYC, ou seja, é necessário fazer um novo envio com o documento informado no campo "pendingReason".)

{
"entity": "kyc",
"createTimestamp": "2023-07-26T21:13:04.856+00:00",
"status": "PENDING",
"body": {
"clientCode": "416bbac2-47b6-4518-8520-a487aedf0e",
"documentNumber": "85467256084",
"onboardingId": "eb616474-87f2-442e-9661-6c8734a0e12e",
"pendingReason": "Motivo da pendencia"
}

Considerações finais

📘

O resultado das análises, tanto da PF quanto da PJ, pode levar até 48h úteis para ser concluída.

👍

Importante

Os retornos das análises do KYC serão direcionados no Webhook disponível na documentação do BaaS. Para mais detalhes sobre os templates, utilize o link recomendado abaixo.

Em casos de reprovação é possível reenviar os documentos pelo mesmo endpoint atual. Após o envio dos documentos, a solicitação terá seu status alterado para "Pendente", e a conta passará por novas análises, podendo ser aprovada ou reprovada. Esta ação implicará em uma nova análise do processo. Os valores de cobrança serão devidamente aplicados conforme os critérios estabelecidos. O reenvio da documentação não garante a aprovação automática do processo de KYC.

Sandbox

No ambiente de sandbox, possuímos o seguinte comportamento:
Caso crie uma conta com final de documento número par, receberá um webhook de approved.
Caso crie uma conta com final de documento ímpar, receberá um webhook de rejected.