Introdução

Este documento tem como objetivo apoiar o cliente a compreender a integração com o produto Onboarding - KYC. Nesse documento iremos explicar o Fluxo, a autenticação e os Endpoints da integração. Para utilização destes serviços é necessário realizar a contratação do Onboarding Celcoin junto a solução do BaaS.
Essa documentação é destinada a clientes que possuem caso de uso ao qual não necessitam do webview para envio dos documentos.

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.

👍

Importante

Sandbox

No ambiente de sandbox, possuímos o seguinte comportamento:
Utilize o campo phoneNumber para PF
Utilize o campo contactNumber para PJ
Final do telefone terminando em:
1 - Aprovado em ambos os webhooks e criará a conta (Independente dos demais dados informados)
2 - Reprovado no primeiro webhook (Independente dos demais dados informados)
3 - Aprova a primeira etapa do processo e reprova a segunda. (Independente dos demais dados informados)
Diferente de telefone final terminado em 1, 2 e 3 seguirá com o cenário próximo da realidade (Necessário informar dados reais em casos desse).
OBS: O comportamento respeitará a configuração utilizada para o seu caso, fluxo 1 ou fluxo 2.

Informações importantes para o processo em produção nas Considerações finais

Fluxo de integração

Essa documentação é destinada a clientes que possuem caso de uso ao qual não necessitam do webview para envio dos documentos.

O primeiro passo é coletar os dados do seu cliente, (detalhados no tópico de Endpoints). Com esses dados coletados, você deverá fazer uma requisição utilizando o método POST em um dos Endpoints disponíveis:
• proposal/natural-person, para contas Pessoa Física (PF)
• proposal/legal-person, para contas Pessoa Jurídica (PJ)
Após essa requisição, será criada uma proposta e iremos rodar uma política de BackgroundCheck em nosso fornecedor e iremos retornar via Webhook o resultado. Caso seja aprovado, além do webhook com o resultado de “Approved” , após a aprovação, serão realizadas novas validações de políticas referente a documentação enviada, como a Documentoscopia e OCR. Iremos retornar o resultado via Webhook e caso seja aprovado, além do webhook iremos também enviar o webhook de criação de conta do BaaS.

Os documentos do cliente deverão ser enviados no request, através de uma URL acessível e atrelada ao download do documento que foi informado no campo "Type".

Recomendações Fluxo

Recomendamos esse fluxo para clientes que possuem já possuem um mecanismo para capturar/recepcionar todos os documentos do cliente.

Criar propostas

A criação das propostas devem ser realizadas através dos endpoints

🙍‍♂️

Pessoa Física

Se a proposta for para uma pessoa física. (onboarding-proposal/natural-person) endpoint

URL Sandbox: https://sandbox.openfinance.celcoin.dev/onboarding/v1/onboarding-proposal/natural-person

Exemplo Request:

form-data

{
  "clientCode": "myUniqueCustomCode",
  "documentNumber": "1234567890",
  "phoneNumber": "+5511999999999",
  "email": "[email protected]",
  "motherName": "My mothers name",
  "fullName": "My full name",
  "socialName": "My social name",
  "birthDate": "01-01-1970",
  "address": {
    "postalCode": "99999000",
    "street": "My address",
    "number": "999",
    "addressComplement": "Address references.",
    "neighborhood": "My neighborhood",
    "city": "My city",
    "state": "State"
  },
  "isPoliticallyExposedPerson": false,
  "onboardingType": "BAAS",
  "files": [ //Devem ser informados todos os documentos no request
    {
      "type": "SELFIE",
      "data": "https://cloud.storage/myselfie_with_1h_expiration_minimum.jpeg" //Essa URL deverá ser acessível e atrelada ao download do documento que foi informado no campo "Type". Recomendamos que essa URL tenha um período de expiração de pelo menos 1 hora.
    }
  ]
}

Exemplo Response:

form-data

{
   "body": {
       "proposalId": "1234cee7-cf18-44d6-ad9c-5a33cd45b9a0", //número da proposta criada
       "clientCode": "myUniqueCustomCode", //código cliente
       "documentNumber": "1234567890" //documento
   },
   "version": "1.0.0", //versão
   "status": "PROCESSING" //status da proposta
}

🏛️

Pessoa Jurídica

Se a proposta for para uma pessoa jurídica. (onboarding-proposal/legal-person) endpoint

É importante informar todos os sócios do Quadro Societário da empresa, ou pelo menos os que possuem participação societária maior ou igual a 25%.

URL Sandbox: https://sandbox.openfinance.celcoin.dev/onboarding/v1/onboarding-proposal/legal-person

Exemplo Request:

form-dataJSON

{
  "clientCode": "123456",
  "contactNumber": "+551239215555",
  "documentNumber": "56461227000199",
  "businessEmail": "[email protected]",
  "businessName": "IP Pagamentos",
  "tradingName": "IPay",
  "companyType": "PJ", //Informe como PJ casos divergentes de MEI e ME.
  "owner": [
    {
      "ownerType": "REPRESENTANTE",
      "documentNumber": "33333333333",
      "fullName": "Carlos Henrique da Silva",
      "phoneNumber": "+5512981175554",
      "email": "[email protected]",
      "motherName": "Nome Sobrenome",
      "socialName": "Nome",
      "birthDate": "31-12-1984",
      "address": {
        "postalCode": "12211400",
        "street": "Rua da Liberdade",
        "number": "313",
        "addressComplement": "Em frente ao parque.",
        "neighborhood": "Casa Verde",
        "city": "São Paulo",
        "state": "SP"
      },
      "isPoliticallyExposedPerson": false
    }
  ],
  "businessAddress": {
    "postalCode": "12211400",
    "street": "Rua da Liberdade",
    "number": "313",
    "addressComplement": "Em frente ao parque.",
    "neighborhood": "Casa Verde",
    "city": "São Paulo",
    "state": "SP"
  },
  "onboardingType": "BAAS",
  "files": [ //Devem ser informados todos os documentos no request
    {
      "type": "RG_FRONT",
      "data": "https://t.ctcdn.com.br/lvns56iaSMyHvyTur4JeYS_NYeY=/i606944.png" //Essa URL deverá ser acessível e atrelada ao download do documento que foi informado no campo "Type". Recomendamos que essa URL tenha um período de expiração de pelo menos 1 hora.
    }
  ]
}

//Exemplo de empresa com sócio PJ, necessário informar o Sócio Administrador da outra empresa.
{
    "clientCode": "a7e9ea3f-69e4-4599-92b4-6cb8a79c3512",
    "contactNumber": "+5511985028123",
    "documentNumber": "42222915000191",
    "businessEmail": "[email protected]}",
    "businessName": "Celcoin",
    "tradingName": "Celcoin Instituição de Pagamento",
    "companyType": "PJ",
    "owner": [
        {
            "ownerType": "SOCIO",
            "documentNumber": "72352781027",
            "fullName": "Nome Socio Primeira Empresa",
            "phoneNumber": "+5511912345128",
            "email": "[email protected]",
            "motherName": "Mother Name Teste",
            "socialName": "Nome",
            "birthDate": "22-06-1972",
            "address": {
                "postalCode": "06455030",
                "street": "Rua do Teste",
                "number": "123",
                "addressComplement": "",
                "neighborhood": "Alphaville Industrial",
                "city": "Barueri",
                "state": "SP"
            },
            "isPoliticallyExposedPerson": false
        },
        {
            "ownerType": "SOCIO",
            "documentNumber": "08006528004",
            "fullName": "Nome Socio da Segunda Empresa",
            "phoneNumber": "+5511912345128",
            "email": "[email protected]",
            "motherName": "Nome Mãe Socio Empresa",
            "socialName": "Nome Social",
            "birthDate": "22-06-2005",
            "address": {
                "postalCode": "06455030",
                "street": "Alameda Xingu",
                "number": "123",
                "addressComplement": "",
                "neighborhood": "Alphaville Industrial",
                "city": "Barueri",
                "state": "SP"
            },
            "isPoliticallyExposedPerson": false
        }
    ],
    "businessAddress": {
        "postalCode": "06454000",
        "street": "Alameda Rio Negro",
        "number": "503",
        "addressComplement": "sala 2020",
        "neighborhood": "Alphaville Centro Industrial",
        "city": "Barueri",
        "state": "SP"
    },
    "onboardingType": "BAAS"
}

No atributo “ownerType” deverá ser informado uma das opções: “SOCIO” OU “REPRESENTANTE”. Para casos onde existe mais de um sócio, utilize a opção "SOCIO" para o primeiro Sócio e a opção “DEMAIS_SOCIOS” para os demais. Caso seja informado REPRESENTANTE será obrigatório a inclusão da Procuração de Poderes.
No atributo CompanyType deverá ser informado o tipo de empresa MEI,ME ou PJ. Em caso de dúvidas, é imprescindível questionar ao cliente, pois impactará na jornada de KYC.

Para casos com empresas com sócio PJ, informe o sócio administrador da segunda empresa no request. Exemplo na guia 2 do Request.

Para casos diferentes de MEI e ME o tipo de empresa, informe como tipo PJ.

Exemplo Response:

form-data

{
    "body": {
        "proposalId": "c3216c8a-df23-450b-92d5-48b0c89c8791", //número da proposta
        "clientCode": "a7e9ea3f-69e4-4599-92b4-6cb8a79c3512", //código cliente
        "documentNumber": "13935893000109" //documento
    },
    "version": "1.0.0", //versão
    "status": "PROCESSING" //status proposta
}

Consultar propostas

É possível consultar as propostas criadas e seus status utilizando o seguinte endpoint

É possível utilizar os seguintes filtros:
• Data início e data fim (Obrigatório caso não inclua o nº da proposta)
• Status proposta
• DocumentNumber
• Nº Proposta

Também é possível consultar os status das Propostas no Painel do Cliente através da opção Consultar Onboarding.

URL Sandbox:
https://sandbox.openfinance.celcoin.dev/onboarding/v1/onboarding-proposal

Exemplo Request:

onboarding-proposal?dateFrom=2024-02-03T06:30:00&dateTo=2024-03-25T06:30:00

Exemplo Response:

form-data

{
    "body": {
        "limit": 200,
        "currentPage": 1,
        "limitPerPage": 200,
        "totalPages": 1,
        "proposal": [
            {
                "proposalId": "8cf4b988-a2f7-4f48-9075-384ca287d993", //número da proposta
                "clientCode": "8904ec29-cf6b-42ea-b8a5-b12aa58b80d2", //código cliente
                "documentNumber": "43512350800", //documento atrelado a proposta
                "status": "RESOURCE_CREATED", //status da proposta
                "proposalType": "PF", //tipo da proposta
                "createdAt": "2024-03-13T14:58:50.073Z", //data de criação da proposta
                "updatedAt": "2024-03-13T14:59:15.512Z", //data de atualização
                "documentscopys": [ //informações referente a documentoscopia da proposta
                    {
                        "documentNumber": "43512350800", //número do documento
                        "status": "APPROVED", //status da documentoscopia
                        "url": "https://cadastro.io/3214bf523eeeb818894ee575e284d8b6", //link da jornada de captura de documentos e facematch
                        "createdAt": "2024-03-13T14:58:52.957Z", //data de criação da documentoscopia
                        "updateAt": "2024-03-13T14:59:20.01Z" //data de atualização da documentoscopia
                    }
                ]
            },
            {
                "proposalId": "253942c5-dbdc-4d1f-b985-28a727d56b81", //número da proposta
                "clientCode": "60a1f00a-b72f-4e99-b7e6-6a59ccf884f7", //código cliente
                "documentNumber": "43561230800", //documento atrelado a proposta
                "status": "PENDING_DOCUMENTSCOPY", //status da proposta
                "proposalType": "PF", //tipo da proposta
                "createdAt": "2024-03-13T14:59:34.142Z", //data de criação da proposta
                "updatedAt": "2024-03-13T15:00:08.856Z", //data de atualização
                "documentscopys": [ //informações referente a documentoscopia da proposta
                    {
                        "documentNumber": "43561230800", //número do documento
                        "status": "PENDING", //status da documentoscopia
                        "url": "https://cadastro.io/444c216bd0a90e1bda19e7a06c923e78", //link da jornada de captura de documentos e facematch
                        "createdAt": "2024-03-13T14:59:34.716Z", //data de criação da documentoscopia
                        "updateAt": "2024-03-13T15:00:09.897Z" //data de atualização da documentoscopia
                    }
                ]
            },
            {
                "proposalId": "7b4bbe6d-d156-4297-b7cc-3db2ba2b5cdc", //número da proposta
                "clientCode": "4cd7589f-a3d1-45c3-8418-9dd86439432c", //código cliente
                "documentNumber": "32113434101", //documento atrelado a proposta
                "status": "RESOURCE_ERROR", //status da proposta
                "proposalType": "PF", //tipo da proposta
                "createdAt": "2024-03-13T16:58:13.215Z", //data de criação da proposta
                "updatedAt": "2024-03-13T16:59:15.771Z", //data de atualização
                "rejectedReason":{ //motivo da reprovação ao criar a conta
                  "errorCode": "CBE123", //código de erro BaaS
                  "message": "error message." //mensagem de erro
                },
                "documentscopys": [
                    {
                        "documentNumber": "91513434101", //número do documento
                        "status": "APPROVED", //status da documentoscopia
                        "url": "https://cadastro.io/444c216bd0a90e1bda19e7a06c913e98", //link da jornada de captura de documentos e facematch
                        "createdAt": "2024-03-13T16:58:14.547Z", //data de criação da documentoscopia
                        "updateAt": "2024-03-13T18:58:14.547Z" //data de atualização da documentoscopia
                    }
                ]
            
            }
        ]
    },
    "version": "1.0.0",
    "status": "SUCCESS"
}

Eventos da jornada do KYC

Evento: onboarding-backgroundcheck

Evento que informa o status do processo de Backgroundcheck.
Status inicial = Pending

//Exemplo Pending
{
  "body": {
    "proposalId": "4915eca3-ad55-467e-973b-05a773290e38",
    "clientCode": "4a3aba31-4c40-411b-a3d9-345e2d43d8ea",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS"
  },
  "createTimestamp": "2024-03-05T16:43:33Z",
  "entity": "onboarding-backgroundcheck",
  "status": "PENDING",
  "webhookId": "9f0587ee-a057-4323-a61c-b89d45acacae"
}

Em caso de aprovação ou reprovação do Backgroundcheck. Status Approved ou Reproved.

//Exemplo Aprovado
{
  "body": {
    "proposalId": "aa3a0bd5-22d3-4454-8bd7-9b9ef1b6da2d",
    "clientCode": "d12304dd-8b16-48a8-a2e9-73f1053252jj",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS"
  },
  "createTimestamp": "2024-03-05T18:02:10Z",
  "entity": "onboarding-backgroundcheck",
  "status": "APPROVED",
  "webhookId": "dce44989-dd518-4abe-85ec-9c863cf39295"
}

//Exemplo Reprovado
{
  "body": {
    "proposalId": "4915eca3-ad55-467e-973b-05a773290e38",
    "clientCode": "4a3aba31-4c40-411b-a3d9-345e2d43d8ea",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS",
    "RejectedReason":[
      "O CPF não está regular na Receita Federal.",
      "CNPJ inativo ou baixado.",
     ]
  },
  "createTimestamp": "2024-03-05T16:43:33Z",
  "entity": "onboarding-backgroundcheck",
  "status": "REPROVED",
  "webhookId": "9f0587ee-a057-4323-a61c-b89d45acacae"
}

Evento: onboarding-documentscopy

Evento que informa o status do processo de Documentoscopia.
Status inicial = Pending

//Exemplo Pending
{
  "body": {
    "proposalId": "aa3a0bd5-22d3-4454-8bd7-9b9ef1b6da2d",
    "clientCode": "d12304dd-8b16-48a8-a2e9-73f1053252ee",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS",
    "urlDocumentscopy": ""
  },
  "createTimestamp": "2024-03-05T18:02:17Z",
  "entity": "onboarding-documentscopy",
  "status": "PENDING",
  "webhookId": "4de73327-ba5a-4240-85d6-8d36e3bf323d"
}

//Exemplo Processing
{
  "body": {
    "proposalId": "aa3a0bd5-22d3-4454-8bd7-9b9ef1b6da2d",
    "clientCode": "d12304dd-8b16-48a8-a2e9-73f1053252ee",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS",
  },
  "createTimestamp": "2024-03-05T18:02:17Z",
  "entity": "onboarding-documentscopy",
  "status": "PROCESSING",
  "webhookId": "4de73327-ba5a-4240-85d6-8d36e3bf323d"
}

Em caso de aprovação ou reprovação da Documentoscopia. Status Approved ou Reproved.

//Exemplo Aprovado
{
  "body": {
    "proposalId": "aa1a0bd5-22d3-4454-8bd7-9b9ef1b6da2d",
    "clientCode": "d12304dd-8b16-48a8-a2e9-73f1053252ee",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS"
  },
  "createTimestamp": "2024-03-06T13:19:40Z",
  "entity": "onboarding-documentscopy",
  "status": "APPROVED",
  "webhookId": "a5c339e8-4021-4ab5-980f-b0d1a28e7fad"
}

//Exemplo Reprovado
{
  "body": {
    "proposalId": "aa1a0bd5-22d3-4454-8bd7-9b9ef1b6da2d",
    "clientCode": "d12304dd-8b16-48a8-a2e9-73f1053252ee",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS",
    "RejectedReason":[
      "O CPF não está regular na Receita Federal.",
      "CNPJ inativo ou baixado.",
     ]
  },
  "createTimestamp": "2024-03-06T13:19:40Z",
  "entity": "onboarding-documentscopy",
  "status": "REPROVED",
  "webhookId": "a5c339e8-4021-4ab5-980f-b0d1a28e7fad"
}

Evento: onboarding-proposal

Resultado da proposta, status Approved ou Reproved.

//Exemplo Aprovado
{
  "body": {
    "proposalId": "aa3a0bd5-22d3-4454-8bd7-9b9ef1b6da2d",
    "clientCode": "d12304dd-8b16-48a8-a2e9-73f1053252ee",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS"
  },
  "createTimestamp": "2024-03-06T13:19:40Z",
  "entity": "onboarding-proposal",
  "status": "APPROVED",
  "webhookId": "412efd4d-5c8f-47fb-b837-71211956b1ef"
}

//Exemplo Reprovado
{
  "body": {
    "proposalId": "bb3a0bd5-22d3-4454-8bd7-9b9ef1b6da2d",
    "clientCode": "d12304dd-8b16-48a8-a2e9-73f1053252ee",
    "documentNumber": "48087438000185",
    "proposalType": "PJ",
    "onboardingType": "BAAS",
    "RejectedReason":[ //motivo da reprovação
      "O CPF não está regular na Receita Federal.",
      "CNPJ inativo ou baixado.",
     ]
  },
  "createTimestamp": "2024-03-06T13:19:40Z",
  "entity": "onboarding-proposal",
  "status": "REPROVED",
  "webhookId": "412efd4d-5c8f-47fb-b837-71211956b1ef"
}

Após a aprovação da proposta, uma conta com os dados respectivos será criada no BaaS e o Webhook do BaaS irá retornar as informações.

Evento: onboarding-create

Criação da conta no BaaS

O Status será sempre CONFIRMED ou ERROR caso ocorra algum erro na criação.

O onboardingId retornado nesse webhook é o mesmo dado do proposalId.

{
  "entity": "onboarding-create",
  "createTimestamp": "2022-11-04T10:35:16.0511474",
  "status": "CONFIRMED",
  "body": {
    "account": {
      "branch": "0001", //agência da conta
      "account": "30053912934", //número da conta
      "name": "Ms. Rodolfo Marvin",
      "documentNumber": "86913161280"
    },
    "onboardingId": "1e39442d-270f-4f9a-b752-9c08456c6e14", //será o mesmo dado do proposalId
    "clientCode": "1f8ff32f-2d1f-4c28-b316-8020b3d13d43",
    "createDate": "2022-11-04T10:35:16.0511474"
  }
}

Tabelas para apoio

Documentos obrigatórios

Parâmetro, possíveis valores e significado

Entidades, possíveis status e significado do status

Regras Campos

Tabela de erros

Considerações finais

❗️

Envio de documentos

Não envie o documento pessoal com mais de uma página, caso mande dessa maneira, será reprovado.

Recomendamos que a URL que contém os documentos tenha um período de expiração de pelo menos 1 hora.

Aceitamos os formatos: PDF, PNG, JPEG

🚧

Requisição individual por proposta

Atualmente não é possível criar diversas contas em uma única requisição, em casos desses é necessário enviar em diferentes requisições.

Quantidade de propostas por documentos
Temos uma validação onde é permitido criar 1 proposta por documento a cada 24 horas. Logo não é possível criar várias propostas para o mesmo documento enquanto a anterior não estiver finalizada e não tenha passado as 24 horas.

Não temos um limitante de aberturas de propostas, apenas se atente todas as regras e orientações descritas nessa documentação.

📘

Resultado das propostas

Em produção, o resultado das análises, tanto da PF quanto da PJ, pode levar até 48horas úteis para ser concluída.

☑️

Validações realizadas

Background Check
• Consulta de CPF/CNPJ na Receita Federal;
• Ações judiciais da Empresa/Pessoa (Processos criminais, trabalhistas, etc);
• Lista de sanções (Nacional: COAF, CEAF, CNEP, MTE, PPE, TSE, CEIS, CEPIM, TCU, Conselho nacional de Justiça. Internacional: EU, FBI, GOV UK, INTERPOL, OFAC, UNSC.);
• Exposição e perfil na mídia;
• Lista PEP;

Documentoscopia
• OCR do documento enviado (Validação dos dados enviados x encontrados na receita x dados do documento enviado);
• Pericia Documental/Documentoscopia;
• Facematch (Validação entre Selfie x Foto documento físico);
• Análise do contrato social e procuração de poderes (Validação da autenticidade do documento e QSA);

👍

Importante

Documentação

PF: Aceitamos documentos físicos originais RG, CNH e RNE (não serão aceitos documentos digitalizados ou cópias autenticadas) e CNH Digital (imprescindível que tenha o QR Code). (Não aceitamos RG Digital).
PJ: Contrato Social ou em casos de clientes MEI, a Certificado da Condição do Microempreendedor Individual (CCMEI) + documentação PF do sócio.

Webhooks

Em caso de não receber o webhook é possível realizar uma chamada para receber o reenvio, para mais informações acesse a documentação de reenvio clicando aqui.

Motivos de Reprovação

O campo RejectedReason nos Webhooks quando a proposta é reprovada, informará o motivo da reprovação.
Caso o motivo não seja permitido por políticas internas resultarão na mensagem: “Cliente reprovado por política de compliance ou regra de negócio."
Para acessar a lista completa, clique aqui.
Os motivos de reprovação não são fixos e podem surgir novos motivos ou alteração na descrição dos mesmos.

ClientCode e ProposalId

ClientCode é um identificador único por transação criado por você.
ProposalId é um identificador único que geramos após a criação da proposta, esse identificador será utilizado para realizar consultas.Recomendamos você guardar esses campos.

Consultar Propostas no Painel do Cliente

É possível consultar os status das Propostas no Painel do Cliente através da opção Consultar Onboarding.

Boas Práticas

Evite a criação de "polling" com períodos curtos nos Endpoints de consulta, o fluxo de onboarding é todo via webhook orientando sempre as alterações de status e em qual etapa do processo a proposta se encontra.