Criação de subcontas

⚠️

Atenção

Todos os novos clientes que desejam criar subcontas via API estarão inicialmente sujeitos ao período de avaliação regulatória para serviços na API. Durante esse período obrigatório, as operações de subcontas e cobranças terão limites definidos. Clique aqui e consulte o funcionamento completo.

A criação de subcontas permite que você crie contas Asaas para seus parceiros, clientes ou estabelecimentos vinculadas a uma conta raiz. Esse modelo é amplamente utilizado em plataformas White Label, marketplaces, ERPs, sistemas de gestão e outras soluções que desejam oferecer os serviços financeiros do Asaas para múltiplos usuários através de uma única integração.

Após a criação da subconta, o titular poderá utilizar normalmente os recursos disponibilizados pelo Asaas através do site, aplicativo ou por meio de uma plataforma integrada desenvolvida por você.

Como resposta da criação da subconta, você receberá:

• A chave de API (apiKey) da subconta criada, necessária para realizar chamadas autenticadas em nome dessa conta.
• O identificador da carteira (walletId), utilizado em recursos como Split de pagamentos e Transferências entre contas Asaas.

Lembrando que, embora as subcontas criadas sob uma conta raiz possam herdar determinadas configurações administrativas e comerciais, algumas configurações precisam ser realizadas individualmente em cada subconta, como webhooks, informações fiscais para emissão de notas e outras configurações operacionais.

📘

Importante

A criação de subcontas pode gerar cobranças de taxas específicas. Consulte Configurações de Conta > Taxas para verificar quais valores se aplicam ao seu contrato.

Quando utilizar subcontas

A criação de subcontas é indicada quando sua plataforma precisa operar para múltiplos clientes mantendo a separação financeira entre eles.

Alguns exemplos comuns incluem:

• Marketplaces que possuem diversos vendedores.
• Plataformas SaaS que oferecem gestão financeira para seus clientes.
• Sistemas White Label.
• ERPs que desejam centralizar a integração financeira dos seus usuários.
• Plataformas que utilizam Split de pagamentos para distribuição automática de valores.

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

Fluxo de criação de uma subconta

Em uma integração típica, a jornada de criação de uma subconta segue o seguinte fluxo:

Criar subconta
↓
Receber apiKey e walletId
↓
Armazenar a apiKey em local seguro
↓
Configurar recursos da subconta
(webhooks, informações fiscais, etc.)
↓
Enviar documentos cadastrais 
↓
Utilizar a apiKey da subconta para realizar operações

Cada etapa possui sua própria finalidade e pode exigir configurações adicionais dependendo do tipo de operação que será realizada posteriormente.

Criação da 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"
}

🚧

Importante

Em Sandbox é possível criar até 20 subcontas por dia. Ao atingir esse limite, novas tentativas retornarão erro.

Além disso, as comunicações relacionadas às subcontas em Sandbox são direcionadas para o e-mail da conta raiz.

Ao criar uma subconta, quando ela não é uma conta BaaS, um e-mail de ativação será enviado para o endereço informado durante o cadastro.

Guardando a chave de API da subconta

As chamadas subsequentes realizadas em nome da subconta deverão utilizar a chave de API retornada na resposta da criação da conta.

A chave de API é disponibilizada apenas neste momento e não poderá ser consultada ou recuperada posteriormente. Por esse motivo, é fundamental armazená-la em um local seguro assim que a subconta for criada.

📘

Boas práticas

• Armazene a apiKey imediatamente após a criação da subconta.
• Evite exibir a chave em logs ou interfaces administrativas.
• Associe internamente a subconta criada ao cadastro correspondente em sua plataforma.
• Utilize mecanismos seguros para armazenamento de credenciais.

Configurações que exigem atenção após a criação

Embora algumas configurações possam ser herdadas da conta raiz, outras precisam ser configuradas individualmente em cada subconta.

Caso sua integração utilize recursos como emissão de notas fiscais, notificações automáticas ou webhooks, recomenda-se realizar essas configurações logo após a criação da conta.

Período de avaliação regulatória - O que é?

O período de avaliação regulatória é uma etapa obrigatória para novas operações de criação de subcontas via API.

Seu objetivo é garantir que a utilização da plataforma esteja em conformidade com os requisitos regulatórios aplicáveis às operações financeiras e às diretrizes estabelecidas pelos órgãos reguladores.

Esse período é iniciado a partir da primeira criação de subconta realizada via API.

Limites durante o período

• Máximo de 10 subcontas de diferentes titulares.
• Máximo de R$ 2.000,00 emitidos em cobranças por subconta.
• Vigência de até 60 dias corridos a partir da primeira subconta criada.

📘

Importante

Após atingir qualquer limite (quantidade, valor ou prazo), a criação de novas subcontas e a emissão adicional de cobranças, assinaturas ou links de pagamento serão bloqueadas até a conclusão do processo de avaliação regulatória.

Restrições importantes

🚧

Importante

Em conformidade com as Resoluções Conjuntas nº 16 e nº 17 do Banco Central para operações de BaaS, a criação de subcontas é permitida apenas para contas de pessoa jurídica (CNPJ). Contas de pessoa física (CPF) não podem criar subcontas.

Próximos passos

Após criar uma subconta, os próximos conteúdos recomendados são:

• Configuração de Webhooks.
• Envio de documentos cadastrais.
• Split de pagamentos.
• Transferências entre contas Asaas.
• Processo de avaliação regulatória.