DiscordStatus
Guias / Guides

Approval of accounts

Even though it is very similar to the production environment, the Sandbox environment requires some precautions to ensure that account and subaccount approvals are processed correctly.

Standalone account approval

In Sandbox, the account is automatically approved at the time of creation, as long as all required business data is filled in correctly.

Make sure the provided data matches the expected field type. For example, avoid using numbers in the Name field.

After submitting the required registration information, validation happens automatically, with no need to manually send documents.

In the test environment, the submitted data does not need to be real. The only requirement is that all mandatory fields are properly completed so the validation can be finalized.

👍

Tip

If you do not want to use real data, you can use tools that generate fictitious company or personal information for testing purposes, such as: https://geradorbr.com/gerador-de-pessoas/

❗

Important

Using numbers or special characters (such as _, #, !, -, among others) may:

  • Prevent automatic account validation
  • Disable PIX
  • Compromise the correct functioning of the integration

Avoid:

Conta Teste_01

Prefer:

Conta Teste Um

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

If the issue persists, contact support.

Subaccounts

In the Sandbox environment, subaccount approval can be performed through the account approval endpoint or by using the auto-approval flow described here.

It is essential to ensure that all required business data is correctly filled in when creating the subaccount.

In addition, the same care must be taken with the subaccount name, using only letters and spaces.

Each subaccount model has specific behavior in the test environment, as described below.

Standard subaccounts

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

To access the subaccount, it is necessary to:

  1. Open the received link
  2. Set the subaccount password
  3. Log in normally

White Label subaccounts

In the White Label model, onboarding must be completed through the onboardingUrl, where the end user submits the required documents.

In the Sandbox environment, this link is for illustrative purposes only and does not represent the full real validation flow that occurs in production.

Updating business data

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

For example, Asaas may insert a default name such as "João da Silva" to allow the update to be completed in the test environment.

Likewise, when accessing the My User tab, you may see information such as CPF, address, or date of birth that you do not recognize.

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

For support, contact: [email protected]


Common errors and best practices

During Sandbox homologation, some issues are quite common. Before contacting support, review the points below.

Using the wrong API Key or environment URL

Make sure the API Key being used matches the correct environment.

  • Sandbox API Key must be used with https://api-sandbox.asaas.com/
  • Production API Key must be used with https://api.asaas.com/

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

Testing operations without available balance

Some flows require a balance in the Sandbox account. In these cases, create and confirm test charges before starting the test.

Expecting identical behavior to the production environment

Although the Sandbox replicates most of the real flow, some steps have specific testing behaviors, such as:

  • automatic approvals
  • manual confirmations
  • use of simulated data
  • testing controls available only in this environment

Using invalid data when creating an account

Names with numbers, special characters, or inconsistent formatting may prevent automatic account approval and affect Pix functionality in the Sandbox.

Testing notifications with third-party data

Email and SMS notifications work normally in the Sandbox. To avoid unintended messages, use only your own contact details during testing.

Ignoring feature-specific limitations

Before considering a flow as validated, check whether it is fully supported in the Sandbox or if there are any documented limitations in this guide.

Before going to production

Before switching your integration to production, make sure:

  • the API URL has been updated to the correct environment
  • the API Key being used is the production key
  • the required features are enabled in the live account
  • the full flow has been validated in the Sandbox
  • your application properly handles responses, failures, and webhooks
  • Sandbox limitations have been considered during homologation

The fact that a flow works in the testing environment does not necessarily mean all production requirements are met. Final validation must consider permissions, feature enablement, and real production behavior.

Next steps

After setting up your Sandbox account, we recommend following this sequence:

  1. generate your Sandbox API Key
  2. point your integration to the Sandbox URL
  3. create a test customer
  4. issue a test charge
  5. confirm the payment to simulate balance
  6. test the specific flows of your integration
  7. validate webhook delivery
  8. review Sandbox limitations before going live
  9. switch to production only after full homologation is completed

Updated 18 days ago