Sandbox

This page brings together frequently asked questions about the Asaas Sandbox environment, focusing on account creation, fictitious balance, features available for testing, and Pix QR Code payment.

Sandbox is a test environment separate from the Production environment. It allows you to validate integration flows without moving real amounts, offering greater security before going into production.

When to use this FAQ

Use this page when you need to clarify questions about:

• Sandbox account creation;
• adding fictitious balance;
• payment simulation;
• Pix QR Code payment testing;
• features available in the test environment;
• Sandbox limitations;
• differences between Sandbox and Production;
• homologation best practices.

1. How do I create my Sandbox account?

Sandbox is a test environment where you can receive fictitious charges and test integrations and Webhooks before using the Production environment.

You can create your Sandbox account at:

https://sandbox.asaas.com/

2. Which features can I test in my Sandbox account?

In the Sandbox environment, you can test several integration flows, such as:

• creating and updating customers;
• creating charges;
• charges by bank slip;
• charges by Pix;
• charges by credit card;
• installment charges;
• payment split;
• transfers;
• transactions;
• Webhooks;
• resource consultation and update flows.

To consult the complete and updated list of features available for testing, access the What can be tested documentation.

3. How can I add balance to my Sandbox account?

In Sandbox, it is possible to add fictitious balance to the account to perform tests.

A common way to do this is to create fictitious customers and fictitious charges. After creating a charge with payment via Bank Slip or Pix, a CONFIRM PAYMENT button will be displayed, allowing you to simulate receiving that charge.

If the charge is by Credit Card and has the status CONFIRMED, the RECEIVE PAYMENT button will be displayed.

Recommended flow:

Create fictitious customer
↓
Create fictitious charge
↓
Access the charge in Sandbox
↓
Confirm or receive the payment through the interface
↓
Validate the fictitious balance
↓
Test the desired flow

4. Is it possible to confirm payment via API in Sandbox?

No.

At the moment, there is no specific endpoint for payment confirmation via API in Sandbox.

To simulate receiving charges, use the buttons available in the Sandbox interface, such as CONFIRM PAYMENT or RECEIVE PAYMENT, according to the type and status of the charge.

5. How to test the Pix QR Code payment functionality in Sandbox?

To test Pix QR Code payment in Sandbox, first create a static Pix QR Code in your Asaas account.

You can use the Create static QR Code reference:

Create static QR Code

When creating the static QR Code, the response will return the payload. This value represents the Pix Copy and Paste content of the QR Code and will be used in the payment call.

After that, copy the returned payload and send this information in the Pay a QR Code call:

Pay a QR Code

Summary flow:

Create static Pix QR Code
↓
Copy the returned payload
↓
Send the payload in the Pay a QR Code call
↓
Validate the payment result
↓
Track the integration update

6. Which fields are important to pay a Pix QR Code?

In the Pix QR Code payment call, the main fields are:

7. Static QR Code creation example

The static QR Code must be created in the Sandbox environment.

Illustrative request example:

{
  "addressKey": "chave-pix-sandbox",
  "description": "Pix QR Code Test",
  "value": 50,
  "format": "ALL",
  "allowsMultiplePayments": true,
  "externalReference": "teste-qrcode-001"
}

Some important fields in static QR Code creation are:

8. Pix QR Code payment example

After creating the static QR Code and obtaining the payload, use the payment call.

Illustrative example:

{
  "qrCode": {
    "payload": "00020126710014br.gov.bcb.pix01362ae3db4c-9f04-44de-9a39-adcc98a334c20209Teste520400005303986540550.005802BR5913Cliente Teste6009Joinville62290525TESTE00000000000001ASA6304DB5E"
  },
  "value": 50,
  "description": "Pix QR Code payment in Sandbox"
}

9. What happens after I pay a Pix QR Code in Sandbox?

When paying a Pix QR Code in Sandbox:

• the payment is processed in the test environment;
• a Pix charge may be created automatically;
• identifiers related to Pix are linked to the charge;
• your integration may receive Webhook events, according to the configuration performed;
• your application can validate status updates and internal reconciliation.

This flow is useful to validate whether the application is prepared to handle Pix receipt and the events generated by Asaas.

10. Which errors can occur when testing Pix QR Code payment?

Some common errors include:

11. Is the balance added in Sandbox real?

No.

The balance displayed in Sandbox is fictitious and is used only for integration tests.

No charge, transfer, payment, or transaction performed in Sandbox generates real financial impact.

12. Can I use the same API Key in Sandbox and Production?

No.

Each environment has its own API Key.

The API Key generated in Sandbox works only in Sandbox. The API Key generated in Production works only in the Production environment.

13. Do Webhooks work in Sandbox?

Yes.

Sandbox allows you to test Webhooks to validate whether your application is correctly receiving and processing the events sent by Asaas.

This test is important to confirm whether your integration updates orders, charges, internal statuses, and other asynchronous flows as expected.

14. When should I migrate my integration to Production?

Migrate to Production only after validating the main flows of your integration in Sandbox.

Before migration, confirm whether:

• customers are created correctly;
• charges are generated with the expected data;
• test payments have been simulated;
• the fictitious balance was sufficient to validate the necessary flows;
• Webhooks were received and processed correctly;
• your application updates internal statuses as expected;
• common errors were handled by the integration;
• the Production API Key was configured in the correct environment.

15. What should I do if a feature is not available in Sandbox?

If a feature is not available for testing in Sandbox, consult the What can be tested documentation to confirm whether there is any known limitation.

If the resource is essential for homologating your integration, contact the Integration Success team to evaluate the scenario.

Best practices

Related content

See also:

• What can be tested;
• Create static QR Code;
• Pay a QR Code;
• Test Pix QR Code payment;
• How to configure your account in Sandbox;
• How to test features in Sandbox;
• Webhooks;
• Testing transfers;
• How to test critical actions.