O processo de KYC é obrigatório para todas as operações de crédito da plataforma e tem como objetivo validar a identidade e a elegibilidade da empresa antes do desembolso.

A plataforma oferece dois modelos de KYC:

Modelo 1 — KYC Embarcado

O KYC embarcado está integrado à esteira de crédito da Celcoin. Ao criar uma operação de crédito (CCB), o processo de verificação é iniciado automaticamente para a empresa vinculada.

O status do KYC é refletido na esteira via webhook pelo evento APPLICATION_STATUS_UPDATED:

• KYC_PROCESSING — verificação em andamento
• CANCELED com status_description: "KYC_REJECTED" — empresa reprovada

Nenhuma chamada adicional é necessária para este modelo.

Antecipação da consulta

É possível antecipar o KYC de uma empresa antes da criação da CCB. Isso permite identificar eventuais reprovações mais cedo no fluxo, evitando que a operação seja criada para uma empresa inelegível.

POST /banking/originator/business/background-check

Body

Exemplo

curl --request POST \
  'https://platform.flowfinance.com.br/banking/originator/business/background-check' \
  --header 'Authorization: Bearer <seu_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "taxpayer_id": "00000000000100",
    "name": "Empresa Teste LTDA"
  }'

Modelo 2 — KYC Externo

Neste modelo, o parceiro é responsável por executar o KYC no próprio ambiente utilizando o provedor de sua preferência. Após a execução, ele deve encaminhar para a plataforma uma hash de evidência que comprove a realização do processo.

A hash é gerada livremente pelo parceiro — não há um formato específico exigido pela plataforma. O importante é que ela identifique unicamente a evidência de KYC executada.

POST /banking/originator/business/background-check/external

Body

Exemplo

curl --request POST \
  'https://platform.flowfinance.com.br/banking/originator/business/background-check/external' \
  --header 'Authorization: Bearer <seu_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "taxpayer_id": "00000000000100",
    "name": "Empresa Teste LTDA",
    "kyc_validation_hash": "hash-gerada-pelo-parceiro"
  }'

Comparativo entre os modelos

Observações

O modelo de KYC utilizado (embarcado ou externo) é definido na configuração do produto junto à Celcoin. Em caso de dúvidas sobre qual modelo está habilitado para o seu produto, consulte seu Gerente de Conta.

Motivos e Tratamento das Reprovações

Quando uma CCB é cancelada em decorrência da análise de KYC, o motivo é disponibilizado no webhook da CCB, seguindo uma nomenclatura padronizada pela Celcoin.

O retorno segue o formato: KYC_DENIED-{REASON}

Quando houver mais de um motivo, os enums serão separados por hífen (-).

Exemplos:

KYC_DENIED-CPF_IRREGULAR

KYC_DENIED-CPF_IRREGULAR-CPF_HOLDER_DECEASED

A alteração é exclusiva para cancelamentos decorrentes da análise de KYC. Os demais motivos de cancelamento da CCB permanecem inalterados.

Motivos e tratamentos

Os motivos apresentados consolidam os cenários atualmente mapeados pela Celcoin.

Importante: a integração deve estar preparada para receber mais de um motivo no mesmo retorno. Quando isso ocorrer, os motivos serão concatenados após KYC_DENIED e separados por hífen (-). Motivos ainda não mapeados serão identificados como UNMAPPED_RESTRICTION.