Contas e KYC

Gerencie contas de vendedor na Chargefy, incluindo verificação de identidade (KYC) para Pessoa Física e Jurídica.

​

Visão Geral

Para receber pagamentos pela Chargefy, cada vendedor precisa de uma conta de vendedor na plataforma. O processo de criação inclui a verificação de identidade (KYC — Know Your Customer), exigida por regulamentação do Banco Central.

Cadastro → Envio de Documentos → Análise KYC → Conta Aprovada → Recebimento de Pagamentos

​

Tipos de Conta

A Chargefy suporta dois tipos de conta, de acordo com a natureza jurídica do vendedor:

​

Pessoa Física (CPF)

Campo	Descrição
first_name	Nome
last_name	Sobrenome
taxpayer_id	CPF (somente números)
birthdate	Data de nascimento (YYYY-MM-DD)
phone_number	Telefone com DDD
email	E-mail do titular
address	Endereço completo

​

Pessoa Jurídica (CNPJ)

Campo	Descrição
business_name	Razão social
business_description	Descrição da atividade
ein	CNPJ (somente números)
business_phone	Telefone comercial
business_email	E-mail comercial
business_address	Endereço da empresa
owner	Dados do representante legal (CPF, nome, etc.)

​

Processo de KYC

O KYC é obrigatório para que a conta seja aprovada e o vendedor possa receber pagamentos. O processo envolve o envio e a validação de documentos.

​

Documentos Necessários

Pessoa Física

Documento	Formatos Aceitos	Obrigatório
Documento de identidade (RG ou CNH)	Frente e verso, JPG/PNG/PDF	Sim
Comprovante de endereço	Conta de luz, água ou telefone (últimos 90 dias)	Sim
Selfie com documento	Foto segurando o documento ao lado do rosto	Sim

Pessoa Jurídica

Documento	Formatos Aceitos	Obrigatório
Contrato social ou estatuto	PDF	Sim
Cartão CNPJ	PDF ou imagem	Sim
Documento do representante legal (RG/CNH)	Frente e verso, JPG/PNG/PDF	Sim
Comprovante de endereço da empresa	Conta de luz, água ou telefone (últimos 90 dias)	Sim

​

Envio de Documentos via SDK

import { Chargefy } from "@chargefy/sdk";

const chargefy = new Chargefy({
  accessToken: process.env.CHARGEFY_ACCESS_TOKEN,
});

// Enviar documento de identidade
const document = await chargefy.accounts.uploadDocument(accountId, {
  type: "identification",
  category: "cnh",
  file: identificationFile, // Buffer ou ReadStream
  description: "CNH do titular",
});

console.log(document.id);        // "doc_abc123"
console.log(document.status);    // "pending_review"

​

Status de Verificação

Cada conta possui um status de verificação que indica o andamento do processo KYC:

Status	Descrição
pending	Documentos ainda não enviados ou aguardando envio
under_review	Documentos enviados e em análise
approved	KYC aprovado — conta habilitada para receber pagamentos
rejected	KYC rejeitado — documentos inválidos ou inconsistentes

Contas com status rejected não podem processar pagamentos. Verifique os motivos da rejeição e reenvie os documentos corrigidos.

​

Consultar Status da Conta

​

Via SDK

import { Chargefy } from "@chargefy/sdk";

const chargefy = new Chargefy({
  accessToken: process.env.CHARGEFY_ACCESS_TOKEN,
});

// Consultar informações da conta
const account = await chargefy.accounts.get(accountId);

console.log(account.id);                  // "acc_xyz789"
console.log(account.type);                // "individual" ou "business"
console.log(account.verification_status); // "approved"
console.log(account.taxpayer_id);         // "123.456.789-00"
console.log(account.created_at);          // "2026-01-15T10:30:00Z"

​

Via API

curl -X GET https://api.chargefy.io/v1/accounts/{account_id} \
  -H "Authorization: Bearer $CHARGEFY_ACCESS_TOKEN"

Resposta:

{
  "id": "acc_xyz789",
  "type": "individual",
  "first_name": "João",
  "last_name": "Silva",
  "taxpayer_id": "12345678900",
  "email": "[e-mail]",
  "verification_status": "approved",
  "verification_details": {
    "identification": "approved",
    "address_proof": "approved",
    "selfie": "approved"
  },
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-18T14:20:00Z"
}

​

Listar Documentos Enviados

const documents = await chargefy.accounts.listDocuments(accountId);

for (const doc of documents.items) {
  console.log(`${doc.type}: ${doc.status}`);
  // "identification: approved"
  // "address_proof: pending_review"
  // "selfie: approved"
}

​

Verificar Pendências

const account = await chargefy.accounts.get(accountId);

if (account.verification_status === "rejected") {
  const details = account.verification_details;

  // Verificar quais documentos foram rejeitados
  for (const [docType, status] of Object.entries(details)) {
    if (status === "rejected") {
      console.log(`Documento rejeitado: ${docType}`);
      console.log(`Motivo: ${details[`${docType}_rejection_reason`]}`);
    }
  }
}

​

Webhooks de Conta

A Chargefy envia webhooks quando o status de verificação de uma conta muda:

Evento	Descrição
account.verification.pending	Documentos enviados e aguardando análise
account.verification.approved	KYC aprovado com sucesso
account.verification.rejected	KYC rejeitado — ação necessária

// Exemplo de handler de webhook
app.post("/webhooks/chargefy", async (req, res) => {
  const event = req.body;

  switch (event.type) {
    case "account.verification.approved":
      console.log(`Conta ${event.data.account_id} aprovada!`);
      // Habilitar funcionalidades de recebimento
      break;

    case "account.verification.rejected":
      console.log(`Conta ${event.data.account_id} rejeitada.`);
      console.log(`Motivo: ${event.data.reason}`);
      // Notificar o vendedor para reenviar documentos
      break;
  }

  res.status(200).json({ received: true });
});

​

Dashboard

No painel da Chargefy, a seção Finanças > Conta exibe:

• Dados cadastrais: Nome, CPF/CNPJ, e-mail e telefone do titular
• Status de verificação: Badge indicando o status atual (pendente, em análise, aprovado ou rejeitado)
• Documentos enviados: Lista com tipo, data de envio e status de cada documento
• Motivos de rejeição: Quando aplicável, exibe o motivo detalhado da rejeição de cada documento
• Ações rápidas: Botão para reenviar documentos rejeitados ou adicionar documentos pendentes

O prazo médio de análise dos documentos é de 1 a 3 dias úteis. Em períodos de alta demanda, pode levar até 5 dias úteis.