Requisitos de KYC

Entenda os tipos de documentos e verificações que cada cliente precisa completar para ser aprovado.

Quando um cliente atinge o status pending_kyc, o array customer.kyc lista todos os documentos e verificações necessários. O fluxo de verificação funciona em duas etapas:

1. Envio antecipado via API (opcional): o parceiro envia pela API os documentos que já possui do cliente (identidade, comprovante de endereço, documentos da empresa, etc.). Isso acelera o processo porque esses documentos já estarão prontos quando o cliente iniciar a sessão de biometria.

2. Sessão de biometria (obrigatória): o parceiro gera uma URL de sessão e a apresenta ao cliente. Na sessão, o cliente envia os documentos restantes, tira a selfie e confirma a submissão. A confirmação é o que dispara a avaliação de todos os documentos.

A selfie só pode ser capturada pelo próprio cliente na sessão de biometria.

Info: O array kyc só está disponível a partir do status pending_kyc. Durante o status creating, o enriquecimento de sócios ainda está em andamento e os requisitos não foram resolvidos.

Todos os requisitos compartilham a mesma estrutura base:

{
  "requirement_id": "identity_12345678900",
  "requirement_type": "identity",
  "label": "Documento de identidade",
  "mandatory": true,
  "subject": {
    "name": "Joao Silva",
    "cpf": "12345678900",
    "subject_type": "applicant"
  },
  "submitted": null
}

Requisitos podem ser vinculados a uma pessoa (sócio ou titular) ou à empresa como um todo.

Requisitos de pessoa incluem o campo subject com os dados de quem deve enviar o documento:

"subject": {
  "name": "Joao Silva",
  "cpf": "12345678900",
  "subject_type": "applicant"
}

O subject_type pode ser:

• applicant para o titular do cadastro
• co_owner para sócios identificados durante o enriquecimento

Requisitos de empresa (como company_document ou articles_of_association) não possuem subject. Eles se aplicam à empresa cadastrada.

Se o parceiro já possui documentos do cliente, pode enviá-los pela API antes da sessão de biometria. Documentos enviados antecipadamente não precisam ser enviados novamente na sessão.

O endpoint POST /v3/customers/{customer_id}/kyc-attachments aceita uploads individuais por requisito. Cada upload precisa dos campos requirement_id, evidence_type, attachment_type e o arquivo.

Tip: O envio antecipado é opcional, mas reduz o que o cliente precisa fazer na sessão de biometria. Quanto mais documentos o parceiro enviar, mais rápido o cliente conclui a verificação.

Documento de identidade com foto de uma pessoa (titular ou sócio). Aceita CNH ou RG como evidência.

CNH (evidence_type: "cnh"): aceita duas formas de envio.

CNH física (frente e verso):

CNH digital (arquivo único):

RG (evidence_type: "rg"):

import fs from "fs";

// CNH física - enviar frente e verso
await client.customers.uploadKycAttachment(customer.id, {
  requirementId: "identity_12345678900",
  evidenceType: "cnh",
  attachmentType: "front",
  file: fs.createReadStream("/path/to/cnh-frente.jpg"),
});

await client.customers.uploadKycAttachment(customer.id, {
  requirementId: "identity_12345678900",
  evidenceType: "cnh",
  attachmentType: "back",
  file: fs.createReadStream("/path/to/cnh-verso.jpg"),
});

Tip: A CNH digital é enviada como um único PDF, sem necessidade de separar frente e verso.

Foto do rosto da pessoa para validação biométrica. Sempre vinculada a um subject.

Warning: A selfie só pode ser capturada pelo cliente na sessão de biometria. Não é possível enviar a selfie pela API.

Comprovante de endereço da pessoa. Sempre vinculado a um subject.

await client.customers.uploadKycAttachment(customer.id, {
  requirementId: "proof_of_address_12345678900",
  evidenceType: "proof_of_address",
  attachmentType: "file",
  file: fs.createReadStream("/path/to/comprovante.pdf"),
});

Documento constitutivo da empresa. Requisito sem subject, aplicado à empresa cadastrada.

O evidence_type é ccmei (Certificado da Condição de Microempreendedor Individual).

await client.customers.uploadKycAttachment(customer.id, {
  requirementId: "company_document",
  evidenceType: "ccmei",
  attachmentType: "file",
  file: fs.createReadStream("/path/to/ccmei.pdf"),
});

Requisito composto que exige dois documentos: o registro de EI e o CCMEI. Ambos precisam ser enviados. Sem subject.

O evidence_type para ambos é ei_mei.

// Registro de EI
await client.customers.uploadKycAttachment(customer.id, {
  requirementId: "ei_mei_documents",
  evidenceType: "ei_mei",
  attachmentType: "ei_registration_requirement",
  file: fs.createReadStream("/path/to/registro-ei.pdf"),
});

// CCMEI
await client.customers.uploadKycAttachment(customer.id, {
  requirementId: "ei_mei_documents",
  evidenceType: "ei_mei",
  attachmentType: "ccmei",
  file: fs.createReadStream("/path/to/ccmei.pdf"),
});

Declaração de faturamento da empresa. Sem subject.

await client.customers.uploadKycAttachment(customer.id, {
  requirementId: "income_statement",
  evidenceType: "income_statement",
  attachmentType: "file",
  file: fs.createReadStream("/path/to/faturamento.pdf"),
});

Contrato social ou documento equivalente da empresa. Sem subject.

await client.customers.uploadKycAttachment(customer.id, {
  requirementId: "articles_of_association",
  evidenceType: "articles_of_association",
  attachmentType: "file",
  file: fs.createReadStream("/path/to/contrato-social.pdf"),
});

Ato constitutivo de Empresa Individual de Responsabilidade Limitada. Sem subject.

await client.customers.uploadKycAttachment(customer.id, {
  requirementId: "eireli_incorporation_statement",
  evidenceType: "eireli_incorporation_statement",
  attachmentType: "file",
  file: fs.createReadStream("/path/to/ato-constitutivo.pdf"),
});

Requisito de nível pessoal para coletar o email de co-titulares que precisam assinar digitalmente a CCB. Cada co-titular gera um requisito email_{cpf} com o campo subject identificando a pessoa.

Nota: O email do titular principal já é informado na criação do cliente. Este requisito aparece apenas para co-titulares que precisam assinar a CCB.

O envio é feito pelo endpoint de upload de anexos KYC, usando o campo value em vez de file:

await client.customers.uploadKycAttachment(customer.id, {
  requirementId: "email_12345678900",
  evidenceType: "email",
  attachmentType: "email",
  value: "co-titular@example.com",
});

Após enviar os documentos que já possui (ou mesmo sem enviar nenhum), o parceiro deve gerar uma sessão de biometria e apresentar a URL ao cliente. Na sessão, o cliente envia os documentos pendentes, captura a selfie e confirma a submissão.

A confirmação na sessão de biometria dispara a avaliação de todos os documentos, incluindo os enviados antecipadamente via API.

const session = await client.customers.createBiometricsSession(customer.id);

// Apresente esta URL ao cliente
console.log(session.session_url);
console.log(session.expires_at);  // Expira em 30 minutos

Info: A sessão de biometria expira em 30 minutos. Gere uma nova sessão caso o tempo expire.

Após a confirmação na sessão de biometria, cada requisito passa por revisão. O campo submitted.review_status indica o resultado:

Quando um documento é rejeitado, o campo submitted.review_reason contém o motivo. Envie um novo documento para o mesmo requirement_id para substituir o anterior.

O webhook customer.kyc_updated é disparado sempre que um documento é enviado com sucesso. O payload inclui o array kyc atualizado com o estado de todos os requisitos.

Quando todos os requisitos obrigatórios são aceitos, o status do cliente avança para under_review e depois para active.

• Cadastro e Ofertas para o fluxo completo de onboarding
• Webhooks para configurar os endpoints de notificação