Qual diferença de uma subconta de um cliente BaaS para uma subconta não-BaaS?

Entenda quando usar subcontas BaaS ou não-BaaS, quais responsabilidades mudam em cada modelo e como seguir o fluxo de criação via API.

Subcontas permitem criar contas Asaas para parceiros, clientes ou estabelecimentos vinculados a uma Conta Pai. Cada subconta pode ter sua própria gestão financeira, clientes, cobranças, transferências, saldo e configurações operacionais.

Antes de começar

Antes de criar subcontas pela API:

1. Confirme com seu gerente de contas se sua operação deve usar o modelo BaaS ou não-BaaS.
2. Configure a conta de sandbox para testar o fluxo de criação, envio de documentos, webhooks e consulta cadastral.
3. Separe os dados cadastrais do titular da subconta, incluindo documento, e-mail, telefones e endereço.
4. Defina quais eventos sua aplicação precisa receber por webhook para acompanhar a operação da subconta.
5. Prepare um local seguro para armazenar a apiKey retornada na criação da subconta.

Escolha o modelo de subconta

Use esta comparação para decidir qual modelo atende melhor sua integração.

No modelo não-BaaS, a subconta acessa a interface do Asaas com as funcionalidades disponíveis para ela. Subcontas nesse formato são originadas do formato Correspondente Bancário.

No modelo BaaS, o Tomador — cliente responsável pela Conta Pai — integra o Asaas ao próprio sistema usando a API e o produto BaaS Asaas. Nesse cenário, o cliente final não precisa acessar a conta no Asaas para gestão ou acompanhamento das informações.

Fluxo de integração BaaS

Siga este fluxo quando sua operação estiver habilitada para BaaS:

1. Solicite ao seu gerente de contas a liberação e o alinhamento da funcionalidade BaaS.
2. Configure sua conta de sandbox para validar a criação de subcontas antes de operar em produção.
3. Crie a subconta pela API usando o endpoint POST /v3/accounts.
4. Configure webhooks já na criação da subconta para acompanhar eventos de criação e atualização sem depender de configurações manuais posteriores.
5. Armazene a apiKey retornada na criação da subconta em local seguro, pois ela será usada nas chamadas autenticadas em nome da subconta.
6. Armazene o walletId retornado caso sua integração use recursos como Split de pagamentos ou transferências entre contas Asaas.
7. Envie a documentação cadastral da subconta pelo fluxo de onboarding com envio de documentos via link.
8. Consulte a situação cadastral da subconta antes de liberar operações financeiras para o cliente final.
9. Implemente, no seu próprio sistema, as telas, avisos e ferramentas de gestão que o cliente final usará.

Criar subconta
↓
Receber apiKey e walletId
↓
Armazenar credenciais com segurança
↓
Configurar webhooks e recursos operacionais
↓
Enviar documentos cadastrais
↓
Consultar situação cadastral
↓
Operar em nome da subconta pela API

Exemplo de criação com webhooks

Use o endpoint POST /v3/accounts para criar uma subconta. Consulte a referência completa de criação de subconta para ver todos os campos, regras e respostas disponíveis.

{
  "name": "Subconta criada via API",
  "email": "[email protected]",
  "cpfCnpj": "66625514000140",
  "birthDate": "1994-05-16",
  "companyType": "MEI",
  "phone": "11 32300606",
  "mobilePhone": "11 988451155",
  "address": "Av. Rolf Wiest",
  "addressNumber": "277",
  "complement": "Sala 502",
  "province": "Bom Retiro",
  "postalCode": "89223005",
  "webhooks": [
    {
      "name": "Webhook para cobranças",
      "url": "http://meusite.com/webhook/payments",
      "email": "[email protected]",
      "sendType": "SEQUENTIALLY",
      "interrupted": false,
      "enabled": true,
      "apiVersion": 3,
      "authToken": "5tLxsL6uoN",
      "events": [
        "PAYMENT_CREATED",
        "PAYMENT_UPDATED",
        "PAYMENT_CONFIRMED",
        "PAYMENT_RECEIVED"
      ]
    }
  ]
}

curl --request POST \
  --url https://api.asaas.com/v3/accounts \
  --header 'Content-Type: application/json' \
  --header 'access_token: SUA_API_KEY_DA_CONTA_PAI' \
  --data '{
    "name": "Subconta criada via API",
    "email": "[email protected]",
    "cpfCnpj": "66625514000140",
    "birthDate": "1994-05-16",
    "companyType": "MEI",
    "phone": "11 32300606",
    "mobilePhone": "11 988451155",
    "address": "Av. Rolf Wiest",
    "addressNumber": "277",
    "complement": "Sala 502",
    "province": "Bom Retiro",
    "postalCode": "89223005",
    "webhooks": [
      {
        "name": "Webhook para cobranças",
        "url": "http://meusite.com/webhook/payments",
        "email": "[email protected]",
        "sendType": "SEQUENTIALLY",
        "interrupted": false,
        "enabled": true,
        "apiVersion": 3,
        "authToken": "5tLxsL6uoN",
        "events": [
          "PAYMENT_CREATED",
          "PAYMENT_UPDATED",
          "PAYMENT_CONFIRMED",
          "PAYMENT_RECEIVED"
        ]
      }
    ]
  }'

Configurar webhooks na criação da subconta ajuda a evitar perda de eventos de criação ou atualização da conta. Os eventos disponíveis estão descritos no guia Sobre os webhooks.

Trate o retorno da criação

Após criar a subconta, sua aplicação deve tratar pelo menos três resultados:

Campos e dados que exigem atenção

A referência da API é a fonte completa para obrigatoriedade, validações e formato de cada campo. Durante a implementação, trate estes dados com atenção:

Esses campos não substituem a consulta à referência da API. Use a referência para validar obrigatoriedade, tipos, formatos aceitos e mensagens de erro antes de concluir sua implementação.

Comportamentos importantes

Ao criar subcontas, considere estes comportamentos na sua jornada de integração:

• Quando uma subconta não-BaaS é criada, o Asaas envia um e-mail de boas-vindas com o link para definição da senha de acesso.
• No modelo BaaS Asaas, nenhuma comunicação é realizada pelo Asaas ao cliente final. A Conta Pai deve realizar as comunicações e disponibilizar os recursos necessários dentro do próprio sistema.
• 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.
• A criação da subconta não substitui o acompanhamento cadastral. Consulte a situação cadastral antes de liberar operações financeiras para o cliente final.
• Novas operações de criação de subcontas via API entram inicialmente no período de avaliação regulatória para serviços na API.
• Durante a avaliação regulatória, há limites de quantidade de subcontas, volume emitido em cobranças por subconta e prazo de vigência. Consulte o FAQ do período de avaliação para ver os detalhes atualizados.

Boas práticas para subcontas BaaS

• Confirme a habilitação do modelo BaaS com seu gerente de contas antes de criar subcontas via API.
• Configure webhooks no momento da criação da subconta para acompanhar eventos desde o início da operação.
• Armazene a apiKey em local seguro assim que ela for retornada e não a exponha em logs, telas administrativas ou mensagens de erro.
• Associe internamente a subconta criada ao cadastro correspondente no seu sistema para evitar divergências operacionais.
• Informe o cliente final sobre as jornadas relevantes dentro do seu próprio sistema, já que ele não receberá comunicações automáticas do Asaas no modelo BaaS.
• Evidencie o Asaas como Instituição Prestadora nos pontos de contato exigidos pela regulamentação aplicável ao modelo BaaS.

Solução de problemas

Use esta lista para tratar falhas comuns durante a implementação:

Impactos operacionais para planejar

Considere estes pontos antes de colocar a integração em produção:

• Conciliação: relacione cada subconta ao cliente final correspondente no seu sistema para conciliar cobranças, transferências, saldos e eventos recebidos.
• Segurança: proteja a apiKey de cada subconta com o mesmo cuidado aplicado à chave da Conta Pai.
• Comunicação: no modelo BaaS, implemente no seu próprio sistema as telas, avisos e notificações que o cliente final precisa receber.
• Operação: planeje a configuração individual de webhooks, informações fiscais e recursos operacionais em cada subconta.
• Regulação: acompanhe os limites e prazos do período de avaliação regulatória antes de escalar a criação de subcontas.

Próximos passos

Aprofunde a implementação nos conteúdos relacionados:

• BaaS com o Asaas
• Criação de subcontas com o BaaS do Asaas
• Referência: criar subconta
• Onboarding e envio de documentos via link
• Sobre os webhooks
• FAQ do período de avaliação regulatória
• Split de pagamentos