Test your integration in the Sandbox

The Sandbox is the Asaas test environment. In it, you can develop and validate your integration without moving real money.

You can test flows such as creating customers, charges, payments, transfers, and Webhooks before using Production credentials.

When to use it

Use the Sandbox to:

• start a new integration;
• test requests without impacting Production;
• validate responses and error handling;
• validate charges, payments, and transactions;
• test receiving and processing Webhooks;
• prepare your application for go-live.

Run the initial tests in the Sandbox and migrate to Production only after validating your integration's flows.

1. Create your Sandbox account

The Sandbox account is independent of the Production account. Even if you already have an Asaas account, you will need to create another one for testing.

After completing sign-up, generate an API key exclusive to this environment.

2. Configure the environment

Use the URL and key that match the environment:

3. Learn how the Sandbox behaves

The Sandbox reproduces most of the platform's flows, but has its own behaviors to make testing easier, such as:

• automatic account approval when the required data is valid;
• manual confirmation of charges;
• use of fictitious cards;
• simulated data in some validations;
• features specific to validation testing.

4. Validate a complete journey

A validation can follow this flow:

Create Sandbox account
        ↓
Generate API key
        ↓
Create customer
        ↓
Create charge
        ↓
Simulate payment
        ↓
Receive Webhook
        ↓
Validate processing

For example, to test receiving a charge payment:

1. Create a customer.
2. Create a charge linked to them.
3. Simulate the payment in the Sandbox.
4. Receive the corresponding Webhook event.
5. Confirm that your application updated the status correctly.

Notifications in the Sandbox

Email and SMS notifications may also be sent in the Sandbox.

Avoid registering random or invalid contacts, as messages may be sent during testing.

Before going to Production

Confirm that your integration:

• uses the correct URL and key;
• handles error responses;
• processes Webhooks idempotently;
• has logging and monitoring;
• does not use fictitious data;
• is prepared for differences between Sandbox and Production;
• has had all critical flows validated.

Next steps

• Set up your account in the Sandbox
• See what can be tested
• Create and manage your API key
• Configure authentication
• Learn about Webhooks