Criação de subcontas

Crie uma subconta vinculada à sua conta-pai para operar clientes, parceiros ou estabelecimentos com separação de saldo, cobranças, clientes e configurações.

Este guia cobre a criação da subconta. Se sua operação utiliza BaaS, siga também o fluxo específico de Criação de subcontas com o BaaS do Asaas.

Quando utilizar

Crie subcontas quando sua integração precisar operar para diferentes titulares mantendo as operações financeiras separadas.

Esse modelo pode atender, por exemplo:

• marketplaces;
• plataformas SaaS;
• ERPs e sistemas de gestão;
• operações com múltiplos estabelecimentos;
• integrações que utilizam Split entre contas Asaas.

Cada subconta possui seus próprios clientes, cobranças, transferências, saldo e configurações operacionais.

Antes de começar

A conta-pai que cria as subcontas deve ser de pessoa jurídica (CNPJ).

Defina também qual modelo será utilizado:

• não-BaaS: o titular recebe acesso à interface do Asaas e conclui sua ativação e documentação por esse fluxo;
• BaaS: a jornada é conduzida pela sua plataforma e exige configuração prévia da operação.

Consulte Detalhamento do Fluxo de Aprovação de Subcontas para comparar os dois modelos.

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Preparar os dados da subconta"] --> B["Criar a subconta"]
    B --> C["Armazenar apiKey<br/>e walletId"]
    C --> D["Configurar recursos<br/>da subconta"]
    D --> E["Concluir ativação<br/>e documentação"]
    E --> F["Operar em nome<br/>da subconta"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B,C,D,E validacao
    class F sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

1. Crie a subconta

POST /v3/accounts
Confira a referência completa deste endpoint

{
    "name": "Subconta criada via API",
    "email": "[email protected]",
    "cpfCnpj": "66625514000140",
    "birthDate": "1994-05-16",
    "companyType": "MEI",
    "phone": "11 32300606",
    "mobilePhone": "11 993367861",
    "address": "Av. Rolf Wiest",
    "addressNumber": "277",
    "complement": "Sala 502",
    "province": "Bom Retiro",
    "postalCode": "89223005"
}

A referência atual também exige o envio de incomeValue. O campo birthDate é aplicável somente quando o titular da subconta for pessoa física; para pessoa jurídica, utilize os campos correspondentes ao cadastro empresarial.

Consulte a API Reference antes da implementação para verificar os campos obrigatórios atuais.

Se sua integração utilizar Webhooks, o campo webhooks permite configurá-los na própria criação da subconta. Prefira essa opção quando os eventos precisarem ser acompanhados desde o início da operação.

Quando a subconta criada não for BaaS, o Asaas envia um e-mail de ativação para o endereço informado no cadastro.

2. Armazene os identificadores retornados

A resposta da criação contém:

• apiKey: chave utilizada para autenticar chamadas em nome da subconta;
• walletId: identificador da carteira da subconta.

O walletId pode ser utilizado em recursos como Split de pagamentos e Transferências entre contas Asaas.

A apiKey é exibida na resposta da criação e deve ser capturada nesse momento.

Durante o período de avaliação, a criação retorna a apiKey da subconta. Para continuar utilizando o gerenciamento de chaves após esse período, a operação deve estar adequada ao BaaS do Asaas ou enquadrada como subcontas de filiais com o mesmo prefixo de CNPJ da conta principal.

Se sua operação utiliza BaaS, consulte Gerenciamento das chaves de API de subcontas.

3. Configure os recursos da subconta

Algumas configurações são específicas de cada subconta e devem ser tratadas conforme os recursos utilizados pela integração.

4. Conclua a ativação e aprovação

O próximo passo depende do modelo da subconta.

Para subcontas não-BaaS, o titular recebe o e-mail de ativação, define sua senha e envia a documentação pela interface do Asaas.

Para subcontas BaaS, siga o processo de Onboarding e envio de documentos via link.

Para acompanhar alterações cadastrais de forma automática em operações integradas, utilize os Webhooks de situação da conta, evitando consultas recorrentes apenas para detectar mudanças de status.

Período de avaliação regulatória

O período de avaliação é iniciado com a primeira criação de subconta em Produção.

Durante esse período:

• a conta-pai pode criar até 10 subcontas;
• cada subconta pode emitir até R$ 2.000,00 em cobranças;
• o período possui duração máxima de 60 dias.

A homologação pode ser solicitada durante o período de avaliação, sem necessidade de aguardar o bloqueio.

Consulte a FAQ do Período de Avaliação para conhecer todas as regras aplicáveis.

Manutenção cadastral

Os dados comerciais da subconta precisam ser confirmados ou atualizados periodicamente.

Consulte Confirmação Anual de Dados Comerciais para Subcontas para implementar essa etapa.

Próximos passos

• Entenda o fluxo de aprovação das subcontas
• Crie subcontas com o BaaS do Asaas
• Realize o onboarding e envio de documentos via link
• Configure os Webhooks de situação da conta
• Consulte a FAQ do Período de Avaliação