Criação de subcontas com o BaaS do Asaas
Use este guia para criar uma subconta dentro de uma operação BaaS já habilitada, configurar Webhooks desde a criação e seguir para o onboarding e aprovação cadastral.
ImportanteO modelo BaaS do Asaas (Antigo "White Label"), para fornecimento de serviços bancários para terceiros (Banking As a Service) agora está sujeito à obrigatoriedade de exposição e identificação do Asaas como Instituição Prestadora, conforme sinalizado pela Resolução Conjunta nº 16/17. Além disso, as novas contas integram-se inicialmente ao período de avaliação regulatória para Serviços na API.
Com o BaaS do Asaas habilitado seu cliente não precisará ter acesso ao nosso sistema e não receberá nenhum tipo de comunicação por parte do Asaas, cabendo a você nesse caso disponibilizar os recursos desejados de nossa documentação API dentro do seu sistema integrado, garantindo, apenas, a conformidade com as regras de empresa Tomadora.
Antes de começar
Para criar subcontas BaaS:
- o modelo BaaS deve estar previamente alinhado e habilitado para sua operação;
- a conta-pai deve ser de pessoa jurídica (CNPJ);
- sua aplicação deve estar preparada para armazenar com segurança a
apiKeyretornada na criação; - em Produção, novas operações de criação de subcontas via API estão inicialmente sujeitas ao período de avaliação regulatória.
AtençãoO formato BaaS precisa estar previamente alinhado e implantado pelo seu gerente de contas. A criação de contas Asaas usando os métodos listados abaixo sem uma definição prévia do funcionamento no formato autorizado, resultará na criação de subcontas fora dessa estrutura.
Em Sandbox, para fazer o teste, basta verificar aqui nessa sessão como configurar na conta sandbox.
Fluxo de implementação
%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
A["Habilitar o BaaS"] --> B["Criar a subconta<br/>com Webhooks"]
B --> C["Armazenar apiKey<br/>e walletId"]
C --> D["Enviar documentos<br/>do onboarding"]
D --> E["Acompanhar situação<br/>por Webhooks"]
E --> F["Subconta aprovada"]
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 e configure os Webhooks
Crie a subconta pela conta-pai:
POST
/v3/accounts
Confira a referência completa deste endpoint
O campo webhooks permite criar a subconta já com as configurações de Webhook necessárias, evitando uma etapa adicional de configuração.
{
"name": "Subconta criada via API",
"email": "[email protected]",
"cpfCnpj": "66625514000140",
"companyType": "MEI",
"phone": "11 32300606",
"mobilePhone": "11 988451155",
"incomeValue": 25000,
"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": "token-seguro-com-mais-de-32-caracteres",
"events": ["PAYMENT_CREATED", "PAYMENT_UPDATED", "PAYMENT_CONFIRMED", "PAYMENT_RECEIVED"]
}
]
}O exemplo configura eventos de cobrança. Para acompanhar o onboarding e a aprovação da subconta, configure também os eventos necessários de situação da conta.
Evite depender de consultas recorrentes à API para detectar mudanças de situação cadastral.
Resultado da criação
A resposta contém informações que devem ser associadas à subconta na sua aplicação, incluindo:
apiKey: credencial utilizada para realizar operações em nome da subconta;walletId: identificador da carteira utilizado em recursos como Split e transferências entre contas Asaas.
A apiKey retornada na criação deve ser armazenada imediatamente em local seguro.
2. Realize o onboarding da subconta
Após criar a conta, envie a documentação necessária para aprovação.
Antes de verificar os documentos pendentes, aguarde pelo menos 15 segundos após a criação da subconta. Esse intervalo permite concluir a validação inicial dos dados cadastrais.
O método de envio depende da presença do atributo onboardingUrl no documento solicitado.
Siga o fluxo completo em Onboarding e envio de documentos via link.
3. Acompanhe a aprovação da subconta
Priorize os Webhooks de situação cadastral para receber automaticamente as mudanças ocorridas durante a análise.
Para identificar a aprovação final, acompanhe o evento ACCOUNT_STATUS_GENERAL_APPROVAL_APPROVED.
Consulte todos os eventos disponíveis em Eventos para verificar situação da conta.
Quando precisar recuperar o estado atual da conta de forma pontual, utilize:
GET
/v3/myAccount/status
A subconta está integralmente aprovada quando o atributo general retorna APPROVED.
Consulte a referência para situação cadastral da conta.
Período de avaliação regulatória
Em Produção, o período de avaliação começa quando a conta-pai cria sua primeira subconta.
Durante esse período:
- podem ser criadas até 10 subcontas;
- cada subconta pode emitir até R$ 2.000,00 em cobranças;
- o período pode durar 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 emissão adicional de cobranças, assinaturas, links de pagamento, será automaticamente bloqueada até a finalização do processo de avaliação regulatória (checklists/documentação).
- No novo cenário regulatório, em cada ponto de contato com seu cliente final (telas próprias, comprovantes, onboarding, contratos), é obrigatório evidenciar a marca, os links e os textos de responsabilidade do Asaas. Consulte o Playbook de adequação do Asaas para detalhes, ele será criado e enviado exclusivamente pra você, pelo nosso time de atendimento.
Clique aqui e consulte o funcionamento completo.
A homologação regulatória pode ser solicitada durante o período de avaliação, sem necessidade de aguardar o atingimento dos limites.
Próximos passos
Updated 9 days ago