Although it is very similar to the production environment, the Sandbox environment has specific behaviors related to account approval, onboarding, and subaccount access.

For this reason, some precautions are necessary to ensure that tests run correctly.

Standalone Account Approval

In Sandbox, accounts created directly in the environment are approved automatically, provided that all required business information is completed correctly.

Make sure that the information provided is compatible with the field type, avoiding, for example:

numbers in the name field;
special characters;
inconsistent data entries.

After the required information is submitted, validation occurs automatically, without the need to manually submit documents.

In the test environment, the data used does not need to be real. Only the complete filling of the required fields is mandatory for the validation to be completed.

👍
Tip
If you do not want to use real data, you can use fake data generators for your tests, such as:
https://geradorbr.com/gerador-de-pessoas/

❗️
Important
The use of numbers or special characters (such as _, #, !, -, among others) in the account name may:

prevent automatic validation;

disable features such as Pix;

compromise the correct functioning of the integration.

Avoid:

Test Account_01

Prefer:

Test Account One

If the account is not approved automatically or Pix appears as disabled, review the registered name, remove numbers and special characters, and update the account information.

If the issue persists, contact support.

Subaccount Approval

In Sandbox, subaccount approval can occur in different ways, depending on the model used in the integration.

Currently, there are three possibilities:

automatic approval through Sandbox settings;
manual approval using a specific approval endpoint;
onboarding flow through onboardingUrl in BaaS operations.

It is essential to ensure that all required business information is completed correctly when creating the subaccount.

Additionally, the subaccount name must follow the same rules applied to standalone accounts, using only letters and spaces.

Approval via Endpoint

Sandbox provides a specific endpoint for approving accounts and subaccounts during testing.

This flow can be used to simulate approvals without depending on the environment's automatic behavior.

Endpoint:

POST /v3/accounts/{id}/approve

Reference: Approve accounts in Sandbox

📘
When to use
This endpoint is especially useful in scenarios where:

automatic approval is not enabled;

the integrator wants to control the approval timing;

it is necessary to simulate behaviors closer to the production environment.

Subaccount Auto-Approval

It is also possible to enable the auto-approval feature in Sandbox.

In this model, new subaccounts are approved automatically after creation, provided that the required information has been completed correctly.

The configuration can be performed as described here:

How to configure your Sandbox account

Behavior by Subaccount Type

Each subaccount model has specific behaviors related to onboarding and access in the Sandbox environment.

Standard Subaccounts

When creating a standard subaccount in Sandbox, the password reset link is sent to the email address of the parent account responsible for creating the subaccount.

This behavior exists solely to facilitate testing in the Sandbox environment.

Subaccount access occurs as follows:

the parent account receives the password reset email;
the link is used to set the subaccount password;
after setting the password, login can be performed normally using the subaccount credentials.

❗️
Important
Sending the email to the parent account is a Sandbox-specific behavior and does not exactly represent the operational flow of the production environment.

Subaccounts in BaaS Operations

In BaaS operations, onboarding may occur through the onboardingUrl, where the end user submits the required documents.

In Sandbox, this flow is illustrative and simplified, serving only for integration testing purposes.

The behavior of the test environment does not fully represent all regulatory, registration, and operational validations that exist in production.

📘
Important
In BaaS operations, the onboarding flow, document submission, approval process, and presentation of the provider institution may vary according to:

account type;

regulatory validations;

registration status;

compliance rules;

contractual and operational settings applicable in production.

Business Information Updates

When updating business information for an account or subaccount in Sandbox, some information may be filled automatically during the validation process.

For example, Asaas may insert generic names such as:

John Doe

to allow the testing flow to continue.

Likewise, when accessing the My User section, information such as the following may appear:

CPF;
address;
date of birth.

This data is simulated and used exclusively for the internal operation of the Sandbox environment and does not represent real information.

Common Errors and Best Practices

During Sandbox testing, some issues are recurrent. Before contacting support, review the points below.

Using the Wrong API Key or URL

Verify that the API Key being used corresponds to the correct environment.

Sandbox: https://api-sandbox.asaas.com/
Production: https://api.asaas.com/

Mixing credentials and environments is one of the most common causes of authentication errors and unexpected behavior.

Attempting to Test Operations Without Available Balance

Some flows require an available balance in the Sandbox account.

In these cases:

create test charges;
confirm the payments;
use the generated balance to continue testing.

Expecting Identical Behavior to Production

Although Sandbox replicates a large portion of the real journey, some steps have testing-specific behavior, such as:

automatic approvals;
manual confirmations;
simulated data;
simplified flows;
Sandbox-exclusive testing controls.

Using Invalid Registration Data

Names containing numbers, special characters, or inconsistent information may:

prevent automatic approval;
compromise Pix functionality;
cause failures in features that depend on account validation.

Testing Notifications with Third-Party Data

Email and SMS notifications work normally in Sandbox.

To avoid unintended notifications:

use only your own contact information;
avoid using real third-party data during testing.

Ignoring Feature-Specific Limitations

Before considering a flow tested successfully, verify whether:

the feature has full support in Sandbox;
there are documented specific limitations;
the expected behavior depends on resources available only in production.

Before Going to Production

Before migrating your integration to production, review whether:

the API URL has been changed correctly;
the API Key being used is the production key;
the required resources are enabled in the real account;
the complete flow has been tested;
your application properly handles failures and webhooks;
Sandbox limitations have been taken into consideration.

❗️
Important
The fact that a flow works in Sandbox does not automatically guarantee that all production requirements have been met.
Final validation should consider:

account permissions;

regulatory validations;

enabled resources;

actual production environment behavior.

Next Steps

After configuring your Sandbox account, we recommend following this order:

generate your Sandbox API Key;
point your integration to the Sandbox URL;
create a test customer;
issue a test charge;
confirm the payment to simulate balance;
test the specific integration flows;
validate webhook delivery;
review Sandbox-specific limitations;
switch to production only after complete testing.

For technical support related to integrations:

[email protected]