Creating subaccounts with Asaas BaaS
Use this guide to create a subaccount within an already enabled BaaS operation, configure Webhooks at creation, and move on to onboarding and registration approval.
ImportantThe Asaas BaaS model (formerly "White Label"), for providing banking services to third parties (Banking As a Service), is now subject to the mandatory disclosure and identification of Asaas as the Provider Institution, as indicated by Joint Resolution No. 16/17. In addition, new accounts initially join the regulatory evaluation period for API Services.
With Asaas BaaS enabled, your customer will not need access to our system and will not receive any kind of communication from Asaas. In this case, it is up to you to make the desired features from our API documentation available within your integrated system, only ensuring compliance with the rules for the Contracting company.
Before you start
To create BaaS subaccounts:
- the BaaS model must be aligned and enabled for your operation in advance;
- the parent account must be a business account (CNPJ);
- your application must be prepared to securely store the
apiKeyreturned at creation; - in Production, new subaccount creation operations via API are initially subject to the regulatory evaluation period.
AttentionThe BaaS format must be aligned and deployed in advance by your account manager. Creating Asaas accounts using the methods listed below without prior definition of how they work in the authorized format will result in subaccounts being created outside this structure.
In Sandbox, to test it, just check this section on how to configure it in the sandbox account.
Implementation flow
%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
A["Enable BaaS"] --> B["Create the subaccount<br/>with Webhooks"]
B --> C["Store apiKey<br/>and walletId"]
C --> D["Send onboarding<br/>documents"]
D --> E["Track status<br/>via Webhooks"]
E --> F["Subaccount approved"]
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. Create the subaccount and configure Webhooks
Create the subaccount from the parent account:
POST
/v3/accounts
See the full reference for this endpoint
The webhooks field lets you create the subaccount with the required Webhook configurations already in place, avoiding an additional configuration step.
{
"name": "Subaccount created via API",
"email": "[email protected]",
"cpfCnpj": "66625514000140",
"companyType": "MEI",
"phone": "11 32300606",
"mobilePhone": "11 988451155",
"incomeValue": 25000,
"address": "Av. Rolf Wiest",
"addressNumber": "277",
"complement": "Room 502",
"province": "Bom Retiro",
"postalCode": "89223005",
"webhooks": [
{
"name": "Webhook for payments",
"url": "http://meusite.com/webhook/payments",
"email": "[email protected]",
"sendType": "SEQUENTIALLY",
"interrupted": false,
"enabled": true,
"apiVersion": 3,
"authToken": "secure-token-with-more-than-32-characters",
"events": ["PAYMENT_CREATED", "PAYMENT_UPDATED", "PAYMENT_CONFIRMED", "PAYMENT_RECEIVED"]
}
]
}The example configures payment events. To track the subaccount's onboarding and approval, also configure the required account status events.
Avoid relying on recurring API queries to detect changes in registration status.
Creation result
The response contains information that must be associated with the subaccount in your application, including:
apiKey: credential used to perform operations on behalf of the subaccount;walletId: wallet identifier used in features such as Split and transfers between Asaas accounts.
The apiKey returned at creation must be stored immediately in a secure location.
2. Complete the subaccount onboarding
After creating the account, send the documentation required for approval.
Before checking the pending documents, wait at least 15 seconds after creating the subaccount. This interval allows the initial validation of the registration data to complete.
The submission method depends on whether the onboardingUrl attribute is present in the requested document.
Follow the complete flow in Onboarding and sending documents via link.
3. Track the subaccount approval
Prioritize the registration status Webhooks to automatically receive changes that occur during the review.
To identify the final approval, track the ACCOUNT_STATUS_GENERAL_APPROVAL_APPROVED event.
See all available events in Events to check account status.
When you need to retrieve the account's current status on demand, use:
GET
/v3/myAccount/status
The subaccount is fully approved when the general attribute returns APPROVED.
See the reference for the account registration status.
Regulatory evaluation period
In Production, the evaluation period starts when the parent account creates its first subaccount.
During this period:
- up to 10 subaccounts can be created;
- each subaccount can issue up to R$ 2,000.00 in charges;
- the period can last up to 60 calendar days from the first subaccount created.
Important
- After reaching any limit (quantity, amount, or time), creating new subaccounts and issuing additional charges, subscriptions, and payment links will be automatically blocked until the regulatory evaluation process (checklists/documentation) is completed.
- In the new regulatory scenario, at every touchpoint with your end customer (your own screens, receipts, onboarding, contracts), it is mandatory to display the Asaas brand, links, and responsibility statements. See the Asaas compliance Playbook for details; it will be created and sent exclusively to you by our support team.
Click here to see how it works in full.
Regulatory approval can be requested during the evaluation period, without having to wait for the limits to be reached.
Next steps
Updated 11 days ago