Creating subaccounts

⚠️

Attention

All new customers who wish to create subaccounts through the API will initially be subject to the regulatory evaluation period for API services. During this mandatory period, subaccount operations and payment creation will be subject to predefined limits. Click here to learn more about how this process works.

Creating subaccounts allows you to create Asaas accounts for your partners, customers, or merchants linked to a parent account. This model is widely used by White Label platforms, marketplaces, ERP systems, management software, and other solutions that want to offer Asaas financial services to multiple users through a single integration.

After the subaccount is created, its owner will be able to use the available Asaas features through the web platform, mobile application, or through an integrated platform developed by you.

As a response to the subaccount creation request, you will receive:

• The subaccount API key (apiKey), required to perform authenticated requests on behalf of that account.
• The wallet identifier (walletId), used by features such as Payment Split and Transfers Between Asaas Accounts.

Keep in mind that although subaccounts created under a parent account may inherit certain administrative and commercial settings, some configurations must be performed individually for each subaccount, such as webhooks, tax information for invoice issuance, and other operational settings.

📘

Important

Creating subaccounts may incur specific fees. Check Account Settings > Fees to verify which charges apply to your contract.

When to Use Subaccounts

Subaccounts are recommended when your platform needs to operate on behalf of multiple customers while maintaining financial separation between them.

Common use cases include:

• Marketplaces with multiple sellers.
• SaaS platforms that provide financial management services to customers.
• White Label solutions.
• ERP systems that centralize financial operations for their users.
• Platforms that use Payment Split to automatically distribute funds.

Each subaccount has its own customers, payments, transfers, balance, and operational settings.

Subaccount Creation Flow

In a typical integration, the subaccount creation journey follows the flow below:

Create subaccount
↓
Receive apiKey and walletId
↓
Store the apiKey securely
↓
Configure subaccount resources
(webhooks, tax settings, etc.)
↓
Submit registration documents
↓
Use the subaccount apiKey to perform operations

Each step has its own purpose and may require additional configuration depending on the operations that will be performed later.

Creating a Subaccount

POST /v3/accounts

View the complete endpoint reference

{
    "name": "Subaccount created 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": "Room 502",
    "province": "Bom Retiro",
    "postalCode": "89223005"
}

🚧

Important

In Sandbox environments, you can create up to 20 subaccounts per day. Once this limit is reached, additional requests will return an error.

Additionally, communications related to Sandbox subaccounts are sent to the parent account's email address.

When a subaccount is created and it is not a BaaS account, an activation email will be sent to the email address provided during registration.

Storing the Subaccount API Key

Subsequent requests performed on behalf of the subaccount must use the API key returned in the account creation response.

The API key is only returned at the time the subaccount is created and cannot be retrieved later. Therefore, it is essential to store it securely as soon as the subaccount is created.

📘

Best Practices

• Store the apiKey immediately after creating the subaccount.
• Avoid displaying the key in logs or administrative interfaces.
• Internally associate the created subaccount with the corresponding customer record in your platform.
• Use secure credential storage mechanisms.

Configurations That Require Attention After Creation

Although some settings may be inherited from the parent account, others must be configured individually for each subaccount.

If your integration uses features such as invoice issuance, automatic notifications, or webhooks, it is recommended to configure these resources immediately after creating the account.

Regulatory Evaluation Period - What Is It?

The regulatory evaluation period is a mandatory stage for new subaccount creation operations performed through the API.

Its purpose is to ensure that the platform is being used in compliance with applicable financial regulations and guidelines established by regulatory authorities.

This period begins when the first subaccount is created via API.

Limits During the Evaluation Period

• Maximum of 10 subaccounts with different account holders.
• Maximum of BRL 2,000.00 in issued payments per subaccount.
• Duration of up to 60 calendar days from the creation of the first subaccount.

📘

Important

Once any limit is reached (quantity, value, or duration), the creation of new subaccounts and the issuance of additional payments, subscriptions, or payment links will be blocked until the regulatory evaluation process is completed.

Important Restrictions

🚧

Important

In accordance with Central Bank Joint Resolutions No. 16 and No. 17 regarding Banking as a Service (BaaS) operations, subaccount creation is only allowed for legal entities (CNPJ). Individual accounts (CPF) cannot create subaccounts.

Next Steps

After creating a subaccount, we recommend reviewing the following topics:

• Webhook configuration.
• Registration document submission.
• Payment Split.
• Transfers between Asaas accounts.
• Regulatory evaluation process.