Guia de Subcontas

Confira o Guia de Subcontas para mais informações.

Este endpoint permite criar uma nova subconta vinculada à sua conta raiz. Esse modelo é comumente utilizado por plataformas White Label, marketplaces, ERPs e outras soluções que precisam operar para múltiplos clientes mantendo a separação financeira entre eles.

O objeto de retorno da API conterá a chave de API da subconta criada (apiKey) e o identificador da carteira (walletId), utilizado em recursos como Split de Cobranças e Transferências entre contas Asaas.

A chave de API (apiKey) será devolvida apenas uma vez, na resposta da criação da subconta. Por esse motivo, recomendamos armazená-la imediatamente em local seguro, pois ela não poderá ser consultada novamente posteriormente.

📘

Exemplo de uso

Um cenário comum é a criação automática de uma subconta para cada cliente cadastrado em sua plataforma. Após a criação, a apiKey retornada pode ser armazenada para que futuras operações sejam realizadas diretamente em nome daquela subconta.

🚧

Importante

• 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.

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

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

📘

Informe sempre um CEP válido

O campo postalCode é utilizado para identificar automaticamente a cidade associada ao endereço informado.

Caso o CEP não seja localizado ou seja inválido, a requisição retornará erro 400, indicando que a cidade precisa ser informada.

🛑

Atenção

O envio do faturamento ou renda mensal através do campo incomeValue é obrigatório tanto neste endpoint (/v3/accounts) quanto no endpoint de Atualização de Dados Comerciais (/v3/myAccount/commercialInfo).

Essa informação é utilizada para fins cadastrais e regulatórios. Caso não seja enviada, a criação da subconta não poderá ser concluída.

⚠️

Atenção - Configuração de Webhooks

O campo webhooks permite configurar os webhooks da subconta durante sua criação.

Quando informado, a subconta já será criada com as configurações de webhook desejadas, evitando a necessidade de uma configuração posterior através de chamadas adicionais.

🛑

Atenção - Manutenção Cadastral Anual Obrigatória

Anualmente, os dados comerciais da subconta, como telefone, e-mail, endereço, faturamento/renda e atividade econômica, deverão ser confirmados ou atualizados.

Esse procedimento é um requisito regulatório obrigatório.

Consulte os detalhes completos em Confirmação Anual de Dados Comerciais para Subcontas.

⚠️

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.

Tentativas de criação realizadas por contas pessoa física serão recusadas.