Find answers to the most common questions about developing and testing integrations in the Asaas Sandbox.

The Sandbox lets you test most API flows without moving real money. However, some features have specific behaviors, limitations, or prerequisites that differ from Production.

Environment and access

1 - What is the difference between Sandbox and Production?

The Sandbox is the environment used to develop and test integrations without moving real money.

Production is the environment used for real operations and is subject to the registration, regulatory, commercial, and operational validations that apply to the account.

2 - Do I need to create a specific account for the Sandbox?

Yes.

The Sandbox account is independent from the Production account. Even if you already have an active Asaas account, you will need to create another one to run tests.

Create your account at:

https://sandbox.asaas.com/

3 - Can I use the same API key as in Production?

No.

Each environment has independent accounts, data, and API keys.

4 - Is data created in the Sandbox sent to Production?

No.

Customers, payments, subscriptions, settings, Webhooks, and other resources created in the Sandbox are not replicated to Production.

When you go live, you will need to configure the resources again in the production environment.

Balance and financial transactions

5 - How do I add balance to the Sandbox account?

Balance is not made available automatically.

To generate balance:

1. create a test customer;
2. create a Pix or boleto charge;
3. confirm the payment manually;
4. use the amount made available in the other tests.

Create customer
      ↓
Create charge
      ↓
Confirm the payment
      ↓
Add balance
      ↓
Run the tests

See Add balance to your Sandbox account.

6 - Do payments made in the Sandbox move real money?

No.

Operations are recorded for testing only. No real money is moved and no financial institution is involved.

7 - Why does a transfer or payment return insufficient balance?

Some operations require available balance, such as:

• Pix transfers;
• TED transfers;
• bill payments;
• anticipations;
• other financial transactions.

Before running the operation, check the account balance and, if needed, confirm a test charge.

Webhooks and notifications

8 - Do Webhooks work in the Sandbox?

Yes.

You can configure Webhooks and use Sandbox events to validate:

• notification receipt;
• internal status updates;
• asynchronous processing;
• idempotency;
• failures and reprocessing.

9 - Can I test email and SMS notifications?

Yes.

Use only your own or authorized emails and phone numbers for testing.

Do not register real third-party data or random contacts, as notifications may be sent during testing.

10 - Can I test WhatsApp notifications?

No.

WhatsApp notifications are not sent in the Sandbox due to the messaging cost involved.

Credit card

11 - Can I test credit card payments?

Yes.

Use the cards provided for testing.

Simulate approval

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

Simulate decline

Mastercard: 5184019740373151
Visa: 4916561358240741

Use only fictitious data for the cardholder.

See Test credit card payments in the Sandbox.

12 - Can I test card tokenization?

Yes.

Tokenization can be enabled in the Sandbox account settings and used to test future charges without resending the card data.

Availability in the Sandbox does not mean it is automatically enabled in Production.

Transfers

13 - Can I test Pix transfers?

Yes, with different behaviors depending on the destination used.

Fictitious test Pix key

Lets you validate sending and debiting the transfer. The amount is not credited to another account.

Key from another Sandbox account

Lets you validate:

• debit in the source account;
• credit in the destination account;
• balance updates;
• reconciliation between the accounts.

See Test transfers in the Sandbox.

14 - Can I test TED transfers?

Yes.

After creating the TED, use the controls available in the Sandbox to:

• confirm the transfer;
• simulate a failure.

These controls are exclusive to the test environment.

Pix and QR Codes

15 - Can I test paying a Pix QR Code?

Yes, as long as the QR Code is compatible with the scenarios available in the Sandbox.

The recommended flow is:

1. use a Sandbox account to create the QR Code;
2. get the returned payload;
3. use another Sandbox account, with balance, to make the payment;
4. validate the debit, the receipt, the statuses, and the Webhooks.

See Test Pix QR Code payments.

16 - Why do I get a 404 error when paying a Pix QR Code?

The 404 Not Found error can occur when:

• the account that generated the QR Code does not have a registered Pix key;
• the payload was not registered in the Sandbox;
• the charge was created in a scenario incompatible with this test;
• a QR Code created before the Pix key was registered was used.

To fix it:

1. register a Pix key in the Sandbox account;
2. create a new charge or a new QR Code;
3. get the new payload;
4. run the payment again.

17 - Can I remove a Pix key in the Sandbox?

No.

Removing Pix keys is not available for testing in this environment.

Accounts and subaccounts

18 - How does Sandbox account approval work?

Accounts created directly in the Sandbox are approved automatically when the required business data is filled in correctly.

To avoid failures:

• fill in all required fields;
• use values compatible with each field;
• use only letters and spaces in the name;
• avoid numbers and special characters.

Example that may prevent approval:

Test Account_01

Prefer:

Test Account One

See Approve accounts and subaccounts in the Sandbox.

19 - Why is Pix disabled in the Sandbox account?

This can happen when the business data was not validated correctly.

Mainly review:

• required fields not filled in;
• name with numbers;
• name with special characters;
• values incompatible with the expected format.

After correcting the data, wait for a new validation and check the account status again.

20 - Can I approve a subaccount manually?

Yes.

Use the endpoint:

POST /v3/accounts/{id}/approve

See the endpoint: Approve account in the Sandbox.

You can also enable auto-approval in the Sandbox settings.

21 - How does access to a standard subaccount work?

In the Sandbox, the password reset link for a standard subaccount is sent to the email of the parent account that created it.

After receiving the email:

1. open the link;
2. set the subaccount password;
3. log in with the subaccount credentials.

This behavior is specific to the Sandbox and may differ in Production.

22 - Can I test BaaS subaccount onboarding?

Yes, with restrictions.

The onboardingUrl field can be used to test filling in the registration and sending the requested information.

However, the Sandbox does not fully reproduce all of Production's registration, regulatory, and operational validations.

Security

23 - What is the critical action token?

It is an additional validation required for certain sensitive operations.

When a critical action is requested in the Sandbox, use:

000000

This token is valid for testing only.

24 - Can I disable the critical action token?

In specific transfer scenarios, the validation can be disabled in the Sandbox by the Integration Success team.

Test the flow with the token enabled first. Disabling it is not the recommended configuration for Production.

See Contact us.

Subscriptions

25 - Can I generate a subscription's charges in advance?

Yes.

Use booklet generation to create the subscription's future charges up to a defined end date.

This feature lets you test:

• charge queries;
• recurrences;
• reports;
• reconciliations;
• synchronizations;
• events that apply to the generated charges.

Booklet generation creates the charges but does not pay them.

See Generate subscription booklet.

Feature availability

26 - Can all features be tested in the Sandbox?

No.

Features can be classified as:

Examples of features with restrictions:

• Pix transfers;
• Pix QR Code payment;
• chargeback testing;
• document submission in BaaS onboarding.

Examples of unavailable features:

• Pix key removal;
• anticipation simulation;
• WhatsApp notifications;
• boleto layout with Pix QR Code;
• some features that depend on external services.

See: See what can be tested in the Sandbox.

Troubleshooting

27 - What are the most common errors in the Sandbox?

• Incorrect API key: Occurs when the key belongs to another environment or account.

• Incorrect URL: Occurs when a Sandbox key is sent to Production or vice versa.

• Insufficient balance: Occurs when the operation requires available funds and the account does not have test balance yet.

• Webhook not received: May be related to the configured URL, authentication, server unavailability, or a response outside the 2xx success range.

• Pix disabled: May be related to invalid or incomplete business data.

• 404 error when paying a Pix QR Code: May occur when the account does not have a Pix key or when the payload was not registered in the Sandbox.

What should I validate before going to Production?

Confirm that:

• success and error flows have been tested;
• Webhooks are processed idempotently;
• the URL was changed to Production;
• the API key belongs to the production environment;
• fictitious data was removed;
• the required features are enabled;
• the key permissions are correct;
• the differences between Sandbox and Production were taken into account;
• registration, regulatory, and operational requirements were validated.

Related content

• Learn about the Sandbox
• Configure your Sandbox account
• Add balance to the Sandbox account
• Test features in the Sandbox
• See what can be tested
• Approve accounts and subaccounts
• Learn about Webhooks
• Create and manage API keys