Subaccounts Guide

Check the Subaccounts Guide for more information.

This endpoint allows you to create a new subaccount linked to your parent account. This model is commonly used by White Label platforms, marketplaces, ERP systems, and other solutions that need to operate on behalf of multiple customers while maintaining financial separation between them.

The API response will contain the newly created subaccount's API key (apiKey) and wallet identifier (walletId), which can be used for features such as Payment Splits and Transfers between Asaas accounts.

The API key (apiKey) is returned only once in the subaccount creation response. For this reason, we strongly recommend storing it securely as soon as it is received, since it cannot be retrieved again later.

📘

Use Case Example

A common scenario is automatically creating a subaccount for each customer registered on your platform. After creation, the returned apiKey can be stored and used to perform future operations directly on behalf of that subaccount.

🚧

Important

• All new customers who wish to create subaccounts via 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.

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

• Additionally, all communications related to Sandbox subaccounts will be sent to the parent account's email address.

📘

Always Provide a Valid Postal Code

The postalCode field is used to automatically identify the city associated with the provided address.

If the postal code cannot be found or is invalid, the request will return a 400 error indicating that the city information is required.

🛑

Attention

Providing the monthly revenue or income through the incomeValue field is mandatory in both this endpoint (/v3/accounts) and the Commercial Information Update endpoint (/v3/myAccount/commercialInfo).

This information is required for registration and regulatory purposes. If it is not provided, the subaccount creation process cannot be completed.

⚠️

Attention - Webhook Configuration

The webhooks field allows you to configure the subaccount's webhooks during its creation.

When provided, the subaccount will already be created with the desired webhook settings, avoiding the need for additional configuration requests afterward.

🛑

Attention - Annual Commercial Information Review Requirement

Every year, the subaccount's commercial information, such as phone number, email address, physical address, revenue/income, and business activity, must be reviewed and confirmed or updated.

This is a mandatory regulatory requirement.

For more details, see Annual Commercial Information Confirmation for Subaccounts.

⚠️

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 entity accounts (CNPJ).
• Individual accounts (CPF) cannot create subaccounts.

Any attempt to create subaccounts from an individual account will be rejected.