Subcontas ValidaPay
Referência
Tudo que você precisa saber sobre subcontas ValidaPay antes de integrar: o que são, como funcionam, quando criar PF ou PJ, o ciclo de aprovação e como operar após a ativação.
Uma subconta não é um cadastro auxiliar.
É uma conta bancária digital completa.
O split fecha a venda.
A subconta mantém o seller autônomo.
Cada seller tem saldo próprio.
Você não precisa repassar manualmente.
Gerenciar subcontas é escalar parceiros —
sem acumular risco no seu caixa.
O que é uma subconta ValidaPay
Uma subconta ValidaPay é uma conta bancária digital completa — com número de conta, agência, código ISPB e chave Pix — criada programaticamente via API e vinculada à sua conta master. Cada subconta tem saldo próprio, extrato próprio, capacidade de receber pagamentos via Pix e pode realizar saques para contas bancárias de mesma titularidade.
A grande diferença em relação a sistemas tradicionais de repasse é que o dinheiro cai diretamente na conta do seller no momento do pagamento, via split automático, sem passar pelo seu caixa primeiro. Isso elimina risco de inadimplência interna, simplifica a conciliação financeira e dá autonomia financeira para cada parceiro da sua plataforma.
O processo de criação é 100% via API. Você envia os dados do titular (CPF ou CNPJ, endereço, dados de renda), a ValidaPay executa o processo de KYC (verificação de identidade exigida pelo Banco Central), e quando aprovada a conta está pronta para operar em minutos.
O que é KYC? KYC (Know Your Customer) é o processo de verificação de identidade exigido pelo Banco Central do Brasil para abertura de contas digitais. A ValidaPay executa esse processo automaticamente com base nos dados enviados via API.
Marketplace
Cada seller recebe sua parte automaticamente no pagamento, sem repasse manual.
SaaS com parceiros
Afiliados e revendedores com conta separada, extrato individual e autonomia financeira.
Franquias e filiais
Cada unidade opera de forma independente, com relatórios financeiros separados.
Plataformas de serviço
Prestadores autônomos recebem por serviço prestado sem você intermediar o pagamento.
Conceitos essenciais
| Conceito | O que é |
|---|---|
| Conta master | Sua conta ValidaPay principal. Todas as subcontas são criadas e gerenciadas por ela. |
| Subconta | Conta bancária digital de um seller/parceiro, vinculada à master. |
| formId | Identificador do processo de onboarding. Retornado na criação, usado para consultar o status. |
| account.number | Número definitivo da conta aprovada. Use como accountId em saldo, saques, extratos e split. |
| Split | Divisão automática do valor de uma cobrança entre a master e subcontas no momento do pagamento. |
Fluxo completo: do cadastro ao primeiro recebimento
O processo tem 6 etapas, da criação da subconta até o primeiro split recebido:
ETAPA 01
Criar subconta
POST /v1/proposals — você envia os dados do seller
ETAPA 02
KYC automático
ValidaPay verifica CPF/CNPJ com os órgãos regulatórios
ETAPA 03
Webhook disparado
Você recebe onboarding.create com o número da conta
ETAPA 04
Salvar número da conta
Persista data.account.number associado ao seller
ETAPA 05
Gerar cobrança com split
Use o número da conta para o seller receber automaticamente
ETAPA 06
Seller recebe
O valor cai na conta do seller no momento do pagamento Pix
Configure o webhook antes de criar subcontas. O número definitivo da conta (data.account.number) é entregue no evento onboarding.create. Sem webhook configurado, você precisará fazer polling com GET /v1/proposals/:formId até a aprovação.
Ciclo de vida e estados
| Status | Significado |
|---|---|
PENDING | Subconta criada, KYC em andamento. A ValidaPay está verificando os dados enviados. |
CONFIRMED | Subconta aprovada e conta bancária criada. O número da conta foi gerado. |
REJECTED | KYC reprovado. Os dados enviados não passaram na verificação regulatória. |
Em produção, a aprovação leva alguns minutos. No sandbox, a aprovação acontece automaticamente após a criação.
PF ou PJ: qual tipo criar?
Ambos usam o mesmo endpoint POST /v1/proposals. A diferença está nos campos do body e no tipo de documento do titular.
| Subconta PF | Subconta PJ | |
|---|---|---|
| Documento | CPF — 11 dígitos, somente números | CNPJ — 14 dígitos, somente números |
| Quando usar | Afiliados, autônomos, freelancers, prestadores individuais | Lojas, empresas, MEIs, franquias — negócio formalizado com CNPJ |
| Campos extras | birthDate obrigatório | companyName, tradingName e legalRepresentative obrigatórios |
| financialDetails | incomeRange — faixa de renda pessoal | estimatedMonthlyRevenue — faturamento mensal estimado |
| Restrição | E-mail e telefone não podem ser os mesmos da conta master em ambos os casos | |
Se o seller é pessoa física autônoma ou afiliado, use PF. Se tem CNPJ (mesmo MEI), use PJ.
Pré-requisitos de integração
- Credenciais da conta master — client_id e client_secret em app.validapay.com.br/integracao/api
- Token com escopos proposals/write (criar) e proposals/read (consultar status)
- URL de webhook acessível publicamente — deve responder HTTP 200 ao receber eventos de onboarding
- Dados completos do seller — nome, documento, e-mail único, telefone único, endereço e renda
- Códigos de financialDetails — consulte a página Campos Financeiros para os códigos corretos
Testando no sandbox
Use a URL https://sandbox.validapay.com.br para todos os testes. No sandbox, a aprovação é automática — você receberá o webhook onboarding.create em segundos. CPF e CNPJ não precisam ser válidos no sandbox.
- Crie uma subconta PF com dados fictícios no sandbox
- Aguarde o webhook
onboarding.createna sua URL de teste - Anote o
data.account.numberretornado - Crie uma cobrança Pix com split para essa subconta
- Simule o pagamento com Pagar em sandbox
- Consulte o saldo da subconta para confirmar o recebimento
O que a API de subcontas permite
| Operação | Descrição |
|---|---|
| Criar subconta PF | Onboarding de titular pessoa física (CPF). |
| Criar subconta PJ | Onboarding de empresa (CNPJ). |
| Status de subconta | Consultar andamento do KYC pelo formId. |
| Listar subcontas | Listar todas as subcontas da master account. |
| Listar cobranças | Cobranças geradas em nome de uma subconta. |
| Saldo subcontas | Consultar saldo de uma ou várias subcontas. |
| Cobrança imediata com split | Gerar cobrança Pix com divisão automática para subconta. |
| Split para Conta Master | Cobrança na subconta com split para a master. |
| Saque subconta | Transferir saldo da subconta via Pix (mesma titularidade). |
| Extrato subconta | Movimentações financeiras de uma subconta. |
Eventos webhook de onboarding
Cadastre estes eventos via POST /v1/users/webhooks ou no painel em Integração → Webhooks (botão + Webhook). Veja sequência, campos e exemplos de payload na página Eventos de Onboarding.
onboarding.backgroundcheckonboarding.documentscopyonboarding.proposalonboarding.createSplit e operações financeiras
Após a subconta ativa, use o número da conta em cobranças com split para que o seller receba automaticamente. Consulte saldo, extrato e saques usando o header accountId com o número da subconta. Saques só são permitidos para contas de mesma titularidade.