> ## Documentation Index
> Fetch the complete documentation index at: https://scaleup-c34c4386.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

> [tab] 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 |

> [tab] 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

```typescript theme={null}
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 |

> [!WARNING]
>
> 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

```typescript theme={null}
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

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

**Resposta:**

```json theme={null}
{
  "id": "acc_xyz789",
  "type": "individual",
  "first_name": "João",
  "last_name": "Silva",
  "taxpayer_id": "12345678900",
  "email": "joao@exemplo.com",
  "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

```typescript theme={null}
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

```typescript theme={null}
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 |

```typescript theme={null}
// 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

> [!NOTE]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.