Creating subaccounts

This additional documentation aims to explain and detail the flowchart for creating Asaas accounts in the White Label format.

Creating subaccounts allows you to create Asaas accounts for your partners/clients linked to a root account, so they can use all Asaas functionalities through our website, app, or through an integrated platform developed by you.

As a response to the creation of the Asaas subaccount, you will receive the API key (apiKey) of the created subaccount to proceed with the integration, and also the walletId if you wish to work with Payment Split or with Transfer between Asaas accounts.

With White Label enabled your client will not have access to our system and will not receive any kind of communication from Asaas, it is up to you in this case to make available the desired resources from our API documentation within your integrated system.

Remember that, although the subaccounts generated under your root account inherit rate settings and management from the root account, other settings must be made individually in each created subaccount, such as webhooks, tax information for invoicing, etc.

The process to start with the creation of subaccounts in white label is summarized in the following steps:

• Request to your account manager for the release of this functionality;
• Creation of the Asaas subaccount with Webhooks being configured;
• Submission of the subaccount documentation, by onboarding with document submission via link;
• Consult the registration situation of the subaccount.

🚧

The White Label format needs to be previously aligned and implemented by your account manager. Creating Asaas accounts using the methods listed below without a prior definition of operation in the White Label format will result in the creation of subaccounts outside this structure.

In Sandbox, to test, just contact Support and request the release.

📘

The creation of subaccounts incurs charges for each account created, check in Account Settings > Fees, which fees apply.

Creation of the subaccount with Webhooks being configured

POST /v3/accounts
Check the complete reference of this endpoint

{
    "name": "Subaccount created via API",
    "email": "[email protected]",
    "cpfCnpj": "66625514000140",
    "birthDate": "1994-05-16",
    "companyType": "MEI",
    "phone": "11 32300606",
    "mobilePhone": "11 988451155",
    "address": "Av. Rolf Wiest",
    "addressNumber": "277",
    "complement": "Room 502",
    "province": "Bom Retiro",
    "postalCode": "89223005",
    "webhooks": [
        {
            "url": "http://localhost:3000/webhook/accountStatus",
            "email": "[email protected]",
            "interrupted": false,
            "enabled": true,
            "apiVersion": 3,
            "authToken": "5tLxsL6uoN",
            "type": "ACCOUNT_STATUS"
        },
        {
            "url": "http://localhost:3000/webhook/transfers",
            "email": "[email protected]",
            "interrupted": false,
            "enabled": true,
            "apiVersion": 3,
            "authToken": "5tLxsL6uoN",
            "type": "TRANSFER"
        },
        {
            "url": "http://localhost:3000/webhook/payments",
            "email": "[email protected]",
            "interrupted": false,
            "enabled": true,
            "apiVersion": 3,
            "authToken": "5tLxsL6uoN",
            "type": "PAYMENT"
        },
        {
            "url": "http://localhost:3000/webhook/invoices",
            "email": "[email protected]",
            "interrupted": false,
            "enabled": true,
            "apiVersion": 3,
            "authToken": "5tLxsL6uoN",
            "type": "INVOICE"
        }
    ]
}

It is of utmost importance that the Webhooks are configured from the start to ensure that no account creation or update event is lost, also avoiding the need for secondary requests for setting up these methods.

Details about the Webhook for Invoices, Transfers, and Fiscal Notes can be found in the API references.

🚧

Important

In Sandbox, it is only possible to create 20 subaccounts per day, if the account reaches the daily limit it will receive an error notification.

In addition, all communications of subaccounts in Sandbox will be sent to the email of the root account. The subaccount owner receives notifications.

Storing the subaccount's API key

The following calls for document submission must be made using the API key of the created subaccount. The key will be returned as a response from the account creation request and must be stored at that time, as it cannot be retrieved later.