Sandbox

Introduction

How to test my integration?

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

In this environment, you can simulate flows such as customer creation, payment generation, webhook handling, payments, transfers, and other platform operations — without moving real money.

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

In this guide, you will find

When to use the Sandbox

You should use the Sandbox whenever you need to:

start developing a new integration
validate API requests without impacting the live environment
test responses, error handling, and webhooks
homologate billing, payment, and fund movement flows
verify that your application is ready for production

We strongly recommend that all initial integration tests are 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, once completed, generate a dedicated API Key for this environment.

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

API environments and URLs

The Sandbox environment is completely 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, always use the API Key and URL that correspond to the same environment:

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

🚧
Always use the Sandbox API Key with the Sandbox URL.
Always use the Production API Key with the Production URL.

How the Sandbox behaves

The Sandbox reproduces most platform flows but includes specific behaviors to facilitate integration testing.

These include:

automatic account approval, as long as required fields are correctly filled
manual confirmation of payment receipts
use of mock credit cards to simulate credit card transactions
simulated data in certain internal validations
features and controls available only in the testing environment

These differences exist to allow full validation of your integration without relying on real financial operations.

🚧
Although the behavior is similar to production, not all features have the same flow or full coverage in the Sandbox.
Always refer to the section What can and cannot be tested before considering a flow fully validated.

Notifications in Sandbox

Sending and receiving email and SMS notifications works normally in the 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 numbers just for testing, as this may compromise proper validation of the notification flow.

Updated 7 days ago