Sandbox

How to test my integration?

The Asaas Sandbox is the API testing environment, created so you can safely develop, validate, and homologate your integration before using production credentials.

In this environment, it is possible to simulate flows such as customer creation, charge issuance, webhook delivery, payments, transfers, and other platform operations without moving real funds.

The goal of the Sandbox is to allow your application to be tested end-to-end before go-live, reducing risks during the transition to production.

In this guide you will find

• When to use Sandbox
• How to create your Sandbox account
• API environments and URLs
• How Sandbox behaves
• How to configure your Sandbox account
• How to add balance for testing
• How to test features in Sandbox
• What can and cannot be tested
• Account and subaccount approval
• Common errors and best practices
• Before going to production

When to use Sandbox

Sandbox should be used whenever you need to:

• start developing a new integration;
• validate API requests without impacting a real environment;
• test responses, error handling, and webhooks;
• homologate billing, payment, and financial movement flows;
• verify whether your application is ready for production.

We recommend that all initial integration tests be performed in this environment before switching to the production API.

How to create your Sandbox account

👍

You can create a Sandbox account at: https://sandbox.asaas.com/

Simply follow the standard account creation flow and, after completing the registration, generate an API Key exclusively for this environment.

The Sandbox account is independent from the production account. Therefore, even if you already use Asaas in a live environment, you will still need to create a separate account for testing.

API environments and URLs

The Sandbox environment is separate from the production environment. This means:

• data created in Sandbox does not exist in production;
• data created in production does not exist in Sandbox;
• access credentials are different;
• configurations made in Sandbox are not replicated to production.

To ensure your tests work correctly, you must use the API Key and URL corresponding to the environment:

🚧

Always use a Sandbox API Key with the Sandbox URL.

Always use a production API Key with the production URL.

How Sandbox behaves

Sandbox reproduces most platform flows but includes specific behaviors designed to facilitate integration homologation.

These include:

• automatic account approval, provided all required business information is completed correctly;
• manual payment confirmation for charges;
• use of test credit cards to simulate card payments;
• simulated data in some internal validations;
• features and controls available exclusively in the testing environment.

These differences exist to allow you to fully validate your integration without relying on real financial operations.

🚧

Although the behavior is similar to the production environment, not all features follow the same flow or have the same level of coverage in Sandbox.

Always consult the What can and cannot be tested section before considering a flow fully homologated.

Example homologation journey

A typical Sandbox testing journey usually follows the flow below:

Create Sandbox account
        ↓
Generate API Key
        ↓
Create customer
        ↓
Create charge
        ↓
Simulate payment
        ↓
Receive webhook
        ↓
Validate application processing

For example, to validate the payment receipt flow through the API, you would typically:

1. Create a customer using the customers endpoint.
2. Create a charge linked to that customer.
3. Simulate the payment of the charge in the Sandbox environment.
4. Receive the webhook corresponding to the payment event.
5. Validate that your application correctly processes the charge status update.

This process allows you to validate the entire communication between your application and Asaas before moving to production.

The details of each testing scenario are available in the specific pages of this guide, such as charge testing, transfers, payments, subscriptions, and webhooks.

Notifications in Sandbox

Sending and receiving email and SMS notifications works normally in Sandbox.

🚧

Do not use real third-party data during testing.

To validate notifications, use only your own email addresses and phone numbers.

Also avoid registering random or invalid phone numbers solely for testing purposes, as this may compromise the correct validation of notification flows.