FAQ - Sandbox

This FAQ gathers the most common questions about the Asaas Sandbox environment.

Sandbox allows you to develop, validate, and test integrations before using them in production, simulating a large portion of the platform's financial flows without moving real funds.

In addition to frequently asked questions, this page presents specific behaviors of the test environment, known limitations, and recommendations for a more efficient testing process.

Important Sandbox Rules

Before starting your tests, consider that:

• Sandbox is completely independent from the Production environment;
• Sandbox and Production API Keys are different;
• data created in Sandbox does not exist in Production;
• some features have specific behaviors for testing purposes;
• certain operations require artificially generated balance for testing;
• not all resources available in Production have full coverage in Sandbox.

What is the difference between Sandbox and Production?

Sandbox is a testing environment.

In Sandbox, it is possible to test integrations, validate webhooks, simulate payments, and reproduce various scenarios without moving real financial resources.

The Production environment processes real operations and is subject to applicable regulatory, commercial, and operational validations.

Do I need to create a specific account for Sandbox?

Yes.

A Sandbox account is independent from a Production account.

Even if you already have an active Asaas account, you must create a separate account for use in the Sandbox environment.

Can I use the same API Key as Production?

No.

Each environment has its own API Key.

❗️

Important

Always use the API Key that corresponds to the environment being used.

How can I generate balance for testing?

Balance is not created automatically.

To generate balance in Sandbox:

1. Create a customer.
2. Create a charge using bank slip or Pix.
3. Manually confirm the payment.
4. Use the received amount to perform your tests.

Simplified flow:

Create customer
↓
Create charge
↓
Confirm payment
↓
Generate balance
↓
Run tests

Do payments performed in Sandbox move real money?

No.

No operation performed in Sandbox generates real financial transactions.

Payment confirmations exist exclusively to allow integration testing.

Do webhooks work normally in Sandbox?

Yes.

Webhook delivery occurs normally during testing.

For this reason, it is recommended to validate:

• event delivery;
• notification processing;
• internal status updates in your application;
• failure handling and reprocessing.

Can I test credit card payments?

Yes.

Sandbox provides specific cards for testing.

Card to simulate success

Number: 4444 4444 4444 4444
CCV: 123
Expiration date: any future date

Cards to simulate failure

Mastercard:
5184019740373151

Visa:
4916561358240741

Can I test Pix transfers?

Yes.

There are two possibilities:

Use BACEN fictitious Pix keys

This allows you to validate transfer submission.

The amount is debited from the Sandbox account but is not credited to any account.

Use another Sandbox account

This allows validation of:

• debit;
• credit;
• balance updates;
• financial reconciliation.

Can I test TED transfers?

Yes.

In Sandbox, TED transfers have manual controls that allow you to:

• confirm the transfer;
• simulate a transfer failure.

These controls exist exclusively for testing purposes.

Can I test Pix QR Codes?

Yes.

The recommended flow consists of:

1. Creating a static Pix QR Code.
2. Obtaining the generated payload.
3. Using the QR Code payment endpoint.
4. Validating the automatically created charge.

Why do I receive a 404 error when paying a Pix QR Code?

This behavior usually occurs when:

• the account does not have a registered Pix key;
• the QR Code payload was not registered in Sandbox;
• the charge was created in a scenario incompatible with testing.

The recommended solution is:

1. register a Pix key in the account;
2. generate a new Pix charge;
3. use the new payload for testing.

How does account approval work in Sandbox?

Accounts created directly in Sandbox are usually approved automatically.

For this to happen:

• all required fields must be completed;
• the name must not contain numbers;
• the name must not contain special characters.

Can I manually approve subaccounts?

Yes.

There is a specific endpoint for approval in Sandbox:

POST /v3/accounts/{id}/approve

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

What is the critical action token?

It is an additional security validation used in sensitive operations.

During Sandbox testing, use:

000000

This token is valid only for testing purposes.

Can I disable the critical action token?

Yes.

In specific scenarios, the Integration Success team can disable this validation for transfer testing in Sandbox.

Can I generate future charges from a subscription?

Yes.

Using the subscription booklet generation feature.

By providing an end date, Asaas creates future subscription charges in advance, allowing you to validate:

• recurrences;
• webhooks;
• reports;
• financial integrations.

Can all features be tested in Sandbox?

No.

Some resources have partial coverage or are unavailable for testing.

Examples:

Available with restrictions

• Pix transfers.
• Chargeback disputes.
• Document submission in BaaS flows.

Not available

• Pix key removal.
• Anticipation simulation.
• WhatsApp notifications.
• Some specific Pix QR Code scenarios.
• Some resources that depend on external integrations.

Always consult the What can be tested? page before starting your testing process.

What are the most common errors?

Using the wrong API Key

This occurs when the key belongs to a different environment.

Using the wrong URL

Sandbox and Production use different URLs.

Testing operations without balance

Transfers, payments, and other flows require available balance.

Not receiving webhooks

This is usually related to the configuration of the receiving endpoint.

Pix disabled on the account

This may occur when the registration contains an invalid name with numbers or special characters.

404 error when paying a Pix QR Code

This usually occurs because there is no registered Pix key or because the payload was not registered in Sandbox.

Best Practices

📘

Recommended

• Test the entire flow before going to production.
• Validate webhooks in addition to synchronous API responses.
• Test both success and failure scenarios.
• Use fictitious data.
• Generate only the balance required for each test.
• Review the specific limitations of each feature.
• Confirm that the required resources are enabled in Production before go-live.

Related Content

• Sandbox.
• How to configure your Sandbox account.
• Adding balance to a Sandbox account.
• How to test features in Sandbox.
• What can be tested?
• Account approval.
• Webhooks.
• API Keys.