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
Pessoa Jurídica
| 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 |
| 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"
{
"id": "acc_xyz789",
"type": "individual",
"first_name": "João",
"last_name": "Silva",
"taxpayer_id": "12345678900",
"email": "[email protected]",
"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.
