---
updatedAt: 2026-10-09T19:53:23.000Z
agentTools:
  projectIndex: https://docs.asaas.com/llms.txt
---

# Sandbox

Introduction

# 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.

<Callout icon="📘" theme="info">
  By the end of this guide, you will have created your Sandbox account, configured authentication, and understood how to validate your integration's main flows.
</Callout>

<Embed title="" typeOfEmbed="youtube" url="https://www.youtube.com/watch?v=YraftCxynLU" href="https://www.youtube.com/watch?v=YraftCxynLU" html="%3Ciframe%20class%3D%22embedly-embed%22%20src%3D%22%2F%2Fcdn.embedly.com%2Fwidgets%2Fmedia.html%3Fsrc%3Dhttps%253A%252F%252Fwww.youtube.com%252Fembed%252FYraftCxynLU%253Ffeature%253Doembed%26display_name%3DYouTube%26url%3Dhttps%253A%252F%252Fwww.youtube.com%252Fwatch%253Fv%253DYraftCxynLU%26image%3Dhttps%253A%252F%252Fi.ytimg.com%252Fvi%252FYraftCxynLU%252Fhqdefault.jpg%26key%3D7788cb384c9f4d5dbbdbeffd9fe4b92f%26type%3Dtext%252Fhtml%26schema%3Dyoutube%22%20width%3D%22854%22%20height%3D%22480%22%20scrolling%3D%22no%22%20title%3D%22YouTube%20embed%22%20frameborder%3D%220%22%20allow%3D%22autoplay%3B%20fullscreen%3B%20encrypted-media%3B%20picture-in-picture%3B%22%20allowfullscreen%3D%22true%22%3E%3C%2Fiframe%3E" />

## 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

<Callout icon="👍" theme="okay">
  <Anchor target="_blank" href="https://sandbox.asaas.com/">Create your Sandbox account</Anchor> and follow the normal sign-up flow.
</Callout>

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:

| Environment | Base URL                           |
| :---------- | :--------------------------------- |
| Sandbox     | `https://api-sandbox.asaas.com/v3` |
| Production  | `https://api.asaas.com/v3`         |

<Callout icon="🚧" theme="warn">
  Accounts, data, settings, and API keys are not shared between Sandbox and Production.

  Always use a Sandbox key with the Sandbox URL and a Production key with the Production URL.
</Callout>

## 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.

<Callout icon="🚧" theme="warn">
  Not all features have the same coverage or the same behavior as in Production.

  See <Anchor target="_blank" href="https://docs.asaas.com/docs/what-can-be-tested">What can and cannot be tested</Anchor> before completing your validation.
</Callout>

## 4. Validate a complete journey

A validation can follow this flow:

```text
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.

<Callout icon="📘" theme="info">
  Validation should not consider only the creation response.

  Also validate status changes, asynchronous events, errors, and reprocessing.
</Callout>

## Notifications in the Sandbox

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

<Callout icon="🚧" theme="warn">
  Do not use real third-party data.

  To test notifications, provide only emails and phone numbers that you are authorized to use.
</Callout>

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

* <Anchor target="_blank" href="https://docs.asaas.com/docs/how-to-set-up-your-account-in-the-sandbox-1">Set up your account in the Sandbox</Anchor>
* <Anchor target="_blank" href="https://docs.asaas.com/docs/what-can-be-tested">See what can be tested</Anchor>
* <Anchor target="_blank" href="https://docs.asaas.com/docs/api-keys">Create and manage your API key</Anchor>
* <Anchor target="_blank" href="https://docs.asaas.com/docs/authentication-2">Configure authentication</Anchor>
* <Anchor target="_blank" href="https://docs.asaas.com/docs/about-webhooks">Learn about Webhooks</Anchor>

# Sub pages

* [How to set up your account in the Sandbox](https://docs.asaas.com/docs/how-to-set-up-your-account-in-the-sandbox-1.md)
* [Adding balance to a Sandbox account](https://docs.asaas.com/docs/adding-balance-to-a-sandbox-account.md)
* [How to test features in the Sandbox](https://docs.asaas.com/docs/how-to-test-features.md)
* [What can be tested?](https://docs.asaas.com/docs/what-can-be-tested.md)
* [Account approval](https://docs.asaas.com/docs/approval-of-accounts.md)
* [FAQ - Sandbox](https://docs.asaas.com/docs/faq-sandbox-1.md)

# Sibling pages

* [Start here](https://docs.asaas.com/docs/start-here.md)
* [Security](https://docs.asaas.com/docs/getting-started-copy.md)
* [MCP Server (AI)](https://docs.asaas.com/docs/mcp-server-ai.md)
* [Payments](https://docs.asaas.com/docs/payments.md)
* [Pix](https://docs.asaas.com/docs/pix-en.md)
* [Automatic Pix](https://docs.asaas.com/docs/automatic-pix-1.md)
* [Subscriptions (recurring)](https://docs.asaas.com/docs/subscription.md)
* [Payment Links](https://docs.asaas.com/docs/payment-links.md)
* [Asaas Checkout](https://docs.asaas.com/docs/asaas-checkout.md)
* [Payment Split](https://docs.asaas.com/docs/payment-split.md)
* [Anticipations](https://docs.asaas.com/docs/anticipations.md)
* [Notifications](https://docs.asaas.com/docs/notifications.md)
* [Transfers](https://docs.asaas.com/docs/transfers.md)
* [Invoices](https://docs.asaas.com/docs/invoices.md)
* [Webhooks](https://docs.asaas.com/docs/webhooks-1.md)
* [Subaccounts](https://docs.asaas.com/docs/subaccounts.md)
* [Bill Payment](https://docs.asaas.com/docs/bill.md)
* [Escrow Account](https://docs.asaas.com/docs/escrow-account-1.md)
* [Plugins/Modules/Partners](https://docs.asaas.com/docs/pluginsmodules.md)
* [Flapp Store](https://docs.asaas.com/docs/flapp-store-en.md)
* [SDK](https://docs.asaas.com/docs/sdks-en.md)
* [Error Library](https://docs.asaas.com/docs/error-library.md)