Confido Docs

Subcontas (Connect)

Crie e gerencie contas de vendedores debaixo da sua, venda em nome delas e mova saldo entre as duas.

Com o Connect, a sua conta (a conta-mãe) cria subcontas para os vendedores da sua plataforma. Cada subconta é uma conta Confido completa, com empresa, loja, saldo e verificação próprios, e passa pela análise da Confido antes de vender e sacar.

Antes de começar: liberar o Connect

O Connect é liberado por conta, pela Confido:

  1. No painel, abra Configurações › Configurações do negócio › Connect (subcontas) e clique em Solicitar. Conte, se quiser, como vai usar as subcontas.
  2. O pedido fica em análise até a Confido aprovar. Se for recusado, o motivo aparece na mesma tela (e chega por e-mail), e você pode pedir de novo.
  3. Aprovado, o menu Connect aparece no painel e as rotas /api/v1/accounts passam a responder.

Antes da aprovação, toda rota de subcontas responde 403 com code: "connect_not_enabled". Conta de pessoa física (CPF) não tem Connect: a resposta é 403 com code: "connect_not_available". A sandbox segue a liberação da conta real.

{
  "statusCode": 403,
  "path": "/api/v1/accounts",
  "code": "connect_not_enabled",
  "message": "O Connect (subcontas) ainda não está liberado para esta conta. Solicite o Connect em Configurações do negócio."
}

Quem pode o quê

Quem O que pode
A mãe direta Gerencia a subconta: dados, verificação, documentos, saldo, saques, links, chaves e vendas em nome dela.
Contas acima da mãe Só leem a árvore (?scope=tree), o detalhe, o saldo e as cobranças.
Qualquer outra conta Recebe 404: para ela a subconta não existe.

A chave precisa dos escopos accounts:read e/ou accounts:write, que não vêm marcados por padrão.

1. Criar a subconta

POST /api/v1/accounts com todos os dados da verificação de uma vez: tipo (individual ou empresa), nome, documento, contato, endereço, sócios, conta bancária e o aceite dos termos (tosAcceptance.accepted: true, que a mãe faz em nome da subconta). O exemplo completo está na Referência.

A resposta (201) traz:

  • account, com o id acct_… e status: "pending";
  • verification, a situação de cada parte;
  • errors, as partes que falharam (a subconta é criada mesmo assim; corrija com PATCH /verification);
  • onboardingUrl, se quiser que o vendedor complete o cadastro sozinho.

O CPF ou CNPJ é único na Confido: um documento que já tem cadastro responde 409.

2. Completar e enviar a verificação

Rota Para quê
GET /api/v1/accounts/{id}/verification Ver o que falta em cada parte.
PATCH /api/v1/accounts/{id}/verification Mandar ou corrigir dados da pessoa, empresa e sócios.
POST /api/v1/accounts/{id}/documents Enviar um documento (multipart: file, kind, ownerId).
POST /api/v1/accounts/{id}/bank-accounts Conta bancária ou chave Pix.
POST /api/v1/accounts/{id}/verification/submit Mandar para análise ({} manda todas as partes prontas).
POST /api/v1/accounts/{id}/onboarding-link Link para o vendedor criar a senha e completar pelo painel.

Aprovada, chega o webhook account.approved (ou account.rejected).

3. Vender em nome da subconta

Mande o cabeçalho Confido-Account com o id da subconta em qualquer venda, cobrança ou link:

curl -X POST https://api.confidoscm.com/api/v1/payments \
  -H "X-API-Key: $CONFIDO_API_KEY" -H "Confido-Account: acct_9xY2kLm0pQs4vWx6" \
  -H "Content-Type: application/json" \
  -d '{ "method": "pix", "currency": "BRL", "amountCents": 5000, "idempotencyKey": "sub-pedido-7",
        "payer": { "name": "Ana Lima", "document": "52998224725", "email": "ana@exemplo.com" } }'

A venda é da subconta e o dinheiro cai no saldo dela. A subconta precisa ser filha direta e estar ativa (neta, de outra árvore ou suspensa: 403). A taxa da sua plataforma vem da configuração da subconta (platformFee).

4. Saldo, transferências e saques

Rota Para quê
GET /api/v1/accounts/{id}/balance Saldo da subconta, em centavos.
POST /api/v1/accounts/{id}/transfers Mover saldo: to_account (da mãe para a subconta) ou from_account (de volta).
POST /api/v1/accounts/{id}/payouts Saque para a conta bancária da própria subconta.
GET /api/v1/accounts/{id}/payments Cobranças da subconta.

Mais rotas

  • GET /api/v1/accounts lista as subcontas (paginado; scope=tree traz a árvore inteira).
  • PATCH /api/v1/accounts/{id}, /suspend, /reactivate e /close (encerra de vez, só com saldo zero e sem pendências).
  • POST /api/v1/accounts/{id}/api-keys gera uma chave própria da subconta.
  • /api/v1/accounts/{id}/webhook-endpoints cadastra webhooks da subconta, ou use connectScope num endpoint seu para receber também os eventos das subcontas (veja Webhooks).