FAQ - Sandbox

Esta FAQ reúne as dúvidas mais comuns sobre o ambiente Sandbox do Asaas.

O Sandbox permite desenvolver, validar e homologar integrações antes da utilização em produção, simulando grande parte dos fluxos financeiros da plataforma sem movimentar valores reais.

Além das perguntas frequentes, esta página apresenta comportamentos específicos do ambiente de testes, limitações conhecidas e recomendações para uma homologação mais eficiente.

Regras importantes do Sandbox

Antes de iniciar os testes, considere que:

• o Sandbox é totalmente independente do ambiente de produção;
• as API Keys de Sandbox e Produção são diferentes;
• os dados criados em Sandbox não existem em Produção;
• algumas funcionalidades possuem comportamentos específicos para homologação;
• determinadas operações exigem saldo gerado artificialmente para testes;
• nem todos os recursos disponíveis em Produção possuem cobertura completa em Sandbox.

Qual a diferença entre Sandbox e Produção?

O Sandbox é um ambiente de homologação.

Nele é possível testar integrações, validar webhooks, simular pagamentos e reproduzir diversos cenários sem movimentar recursos financeiros reais.

Já o ambiente de Produção processa operações reais e está sujeito às validações regulatórias, comerciais e operacionais aplicáveis.

Preciso criar uma conta específica para Sandbox?

Sim.

A conta Sandbox é independente da conta de Produção.

Mesmo que você já possua uma conta ativa no Asaas, será necessário criar uma conta específica para utilização no ambiente Sandbox.

Posso utilizar a mesma API Key da Produção?

Não.

Cada ambiente possui sua própria API Key.

❗️

Importante

Utilize sempre a API Key correspondente ao ambiente utilizado.

Como gerar saldo para testes?

O saldo não é criado automaticamente.

Para gerar saldo em Sandbox:

1. Crie um cliente.
2. Crie uma cobrança via boleto ou Pix.
3. Confirme manualmente o pagamento.
4. Utilize o valor recebido para realizar os testes.

Fluxo simplificado:

Criar cliente
↓
Criar cobrança
↓
Confirmar pagamento
↓
Gerar saldo
↓
Executar testes

Os pagamentos realizados em Sandbox movimentam dinheiro real?

Não.

Nenhuma operação realizada em Sandbox gera movimentação financeira real.

As confirmações de pagamento existem exclusivamente para permitir a homologação da integração.

Os webhooks funcionam normalmente em Sandbox?

Sim.

O envio de webhooks ocorre normalmente durante os testes.

Por esse motivo, recomenda-se validar:

• recebimento dos eventos;
• processamento das notificações;
• atualização dos status internos da aplicação;
• tratamento de falhas e reprocessamentos.

Posso testar pagamentos com cartão de crédito?

Sim.

O Sandbox disponibiliza cartões específicos para homologação.

Cartão para simular sucesso

Número: 4444 4444 4444 4444
CCV: 123
Validade: qualquer data futura

Cartões para simular falha

Mastercard:
5184019740373151

Visa:
4916561358240741

Posso testar transferências Pix?

Sim.

Existem duas possibilidades:

Utilizar chaves Pix fictícias do BACEN

Permite validar o envio da transferência.

O valor é debitado da conta Sandbox, mas não é creditado em nenhuma conta.

Utilizar outra conta Sandbox

Permite validar:

• débito;
• crédito;
• atualização de saldo;
• conciliação financeira.

Posso testar transferências TED?

Sim.

No Sandbox, as TEDs possuem controles manuais que permitem:

• confirmar a transferência;
• simular falha na transferência.

Esses controles existem apenas para homologação.

Posso testar QR Code Pix?

Sim.

O fluxo recomendado consiste em:

1. Criar um QR Code Pix estático.
2. Obter o payload gerado.
3. Utilizar o endpoint de pagamento de QR Code.
4. Validar a cobrança criada automaticamente.

Por que recebo erro 404 ao pagar um QR Code Pix?

Esse comportamento normalmente ocorre quando:

• a conta não possui chave Pix cadastrada;
• o payload do QR Code não foi registrado em Sandbox;
• a cobrança foi criada em um cenário incompatível com a homologação.

A solução recomendada é:

1. cadastrar uma chave Pix na conta;
2. gerar uma nova cobrança Pix;
3. utilizar o novo payload para os testes.

Como funciona a aprovação de contas em Sandbox?

Contas criadas diretamente no Sandbox normalmente são aprovadas automaticamente.

Para que isso aconteça:

• todos os campos obrigatórios devem ser preenchidos;
• o nome não deve conter números;
• o nome não deve conter caracteres especiais.

Posso aprovar subcontas manualmente?

Sim.

Existe um endpoint específico para aprovação em Sandbox:

POST /v3/accounts/{id}/approve

Também é possível habilitar a autoaprovação nas configurações do Sandbox.

O que é o token de ação crítica?

É uma validação adicional de segurança utilizada em operações sensíveis.

Durante os testes em Sandbox, utilize:

000000

Esse token é válido apenas para homologação.

Posso desabilitar o token de ação crítica?

Sim.

Em cenários específicos, o time de Sucesso de Integrações pode desabilitar essa validação para testes de transferências em Sandbox.

Posso gerar cobranças futuras de uma assinatura?

Sim.

Utilizando a funcionalidade de geração de carnê.

Ao informar uma data final, o Asaas cria antecipadamente as cobranças futuras da assinatura, permitindo validar:

• recorrências;
• webhooks;
• relatórios;
• integrações financeiras.

Todas as funcionalidades podem ser testadas em Sandbox?

Não.

Alguns recursos possuem cobertura parcial ou não estão disponíveis para homologação.

Exemplos:

Disponíveis com restrições

• Transferências Pix.
• Contestação de chargeback.
• Envio de documentos em fluxos BaaS.

Não disponíveis

• Remoção de chave Pix.
• Simulação de antecipação.
• WhatsApp.
• Alguns cenários específicos envolvendo QR Code Pix.
• Alguns recursos dependentes de integrações externas.

Consulte sempre a página O que pode ser testado? antes de iniciar a homologação.

Quais são os erros mais comuns?

Utilizar API Key incorreta

Ocorre quando a chave pertence a outro ambiente.

Utilizar a URL errada

Sandbox e Produção possuem URLs diferentes.

Testar operações sem saldo

Transferências, pagamentos e outros fluxos exigem saldo disponível.

Não receber webhooks

Normalmente está relacionado à configuração do endpoint recebedor.

Pix desabilitado na conta

Pode ocorrer quando o cadastro possui nome inválido, contendo números ou caracteres especiais.

Erro 404 ao pagar QR Code Pix

Geralmente ocorre por ausência de chave Pix cadastrada ou payload não registrado no Sandbox.

Boas práticas

📘

Recomendado

• Homologar todo o fluxo antes da entrada em produção.
• Validar webhooks além das respostas síncronas da API.
• Testar cenários de sucesso e falha.
• Utilizar dados fictícios.
• Gerar apenas o saldo necessário para cada teste.
• Revisar as limitações específicas de cada funcionalidade.
• Confirmar que os recursos necessários estão habilitados em Produção antes do go-live.

Conteúdos relacionados

• Sandbox.
• Como configurar sua conta no Sandbox.
• Adicionando saldo em uma conta Sandbox.
• Como testar funcionalidades em Sandbox.
• O que pode ser testado?
• Aprovação de contas.
• Webhooks.
• API Keys.