Creating subaccounts

Create a subaccount linked to your parent account to serve customers, partners, or merchants with separate balances, charges, customers, and settings.

This guide covers subaccount creation. If your operation uses BaaS, also follow the specific flow in Creating subaccounts with Asaas BaaS.

When to use

Create subaccounts when your integration needs to operate for different account holders while keeping financial operations separate.

This model can serve, for example:

• marketplaces;
• SaaS platforms;
• ERPs and management systems;
• operations with multiple merchants;
• integrations that use Split between Asaas accounts.

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

Before you start

The parent account that creates the subaccounts must be a business account (CNPJ).

Also define which model will be used:

• non-BaaS: the account holder gets access to the Asaas interface and completes their activation and documentation through that flow;
• BaaS: the journey is driven by your platform and requires the operation to be configured in advance.

See Detailed Subaccount Approval Flow to compare the two models.

How it works

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Prepare the subaccount data"] --> B["Create the subaccount"]
    B --> C["Store apiKey<br/>and walletId"]
    C --> D["Configure subaccount<br/>features"]
    D --> E["Complete activation<br/>and documentation"]
    E --> F["Operate on behalf<br/>of the subaccount"]

    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

POST /v3/accounts
See the full reference for this endpoint

{
    "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"
}

The current reference also requires sending incomeValue. The birthDate field only applies when the subaccount holder is an individual; for businesses, use the fields corresponding to the business registration.

Check the API Reference before implementing to verify the currently required fields.

If your integration uses Webhooks, the webhooks field lets you configure them when creating the subaccount. Prefer this option when events need to be tracked from the start of the operation.

When the subaccount created is not BaaS, Asaas sends an activation email to the address provided in the registration.

2. Store the returned identifiers

The creation response contains:

• apiKey: key used to authenticate calls on behalf of the subaccount;
• walletId: identifier of the subaccount's wallet.

The walletId can be used in features such as Payment Split and Transfers between Asaas accounts.

The apiKey is shown in the creation response and must be captured at that moment.

During the evaluation period, creation returns the subaccount's apiKey. To keep using key management after this period, the operation must be compliant with Asaas BaaS or qualify as branch subaccounts with the same CNPJ prefix as the main account.

If your operation uses BaaS, see Subaccount API key management.

3. Configure the subaccount features

Some settings are specific to each subaccount and must be handled according to the features used by the integration.

4. Complete activation and approval

The next step depends on the subaccount model.

For non-BaaS subaccounts, the account holder receives the activation email, sets their password, and submits the documentation through the Asaas interface.

For BaaS subaccounts, follow the Onboarding and sending documents via link process.

To automatically track registration changes in integrated operations, use the Account status Webhooks, avoiding recurring queries just to detect status changes.

Regulatory evaluation period

The evaluation period starts with the first subaccount created in Production.

During this period:

• the parent account can create up to 10 subaccounts;
• each subaccount can issue up to R$ 2,000.00 in charges;
• the period lasts a maximum of 60 days.

Approval can be requested during the evaluation period, without having to wait for the block.

See the Evaluation Period FAQ for all applicable rules.

Registration maintenance

The subaccount's business data must be confirmed or updated periodically.

See Annual Business Data Confirmation for Subaccounts to implement this step.

Next steps

• Understand the subaccount approval flow
• Create subaccounts with Asaas BaaS
• Complete onboarding and send documents via link
• Configure the Account status Webhooks
• See the Evaluation Period FAQ