Encontre respostas para as dúvidas mais comuns sobre o desenvolvimento e a homologação de integrações no Sandbox do Asaas.

O Sandbox permite testar grande parte dos fluxos da API sem movimentar valores reais. Entretanto, algumas funcionalidades possuem comportamentos específicos, limitações ou pré-requisitos diferentes de Produção.

Ambiente e acesso

1 - Qual é a diferença entre Sandbox e Produção?

O Sandbox é o ambiente utilizado para desenvolver e homologar integrações sem movimentar valores reais.

Produção é o ambiente utilizado nas operações reais e está sujeito às validações cadastrais, regulatórias, comerciais e operacionais aplicáveis à conta.

2 - Preciso criar uma conta específica para o 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 outra para realizar os testes.

Crie sua conta em:

https://sandbox.asaas.com/

3 - Posso utilizar a mesma chave de API da Produção?

Não.

Cada ambiente possui contas, dados e chaves de API independentes.

4 - Os dados criados no Sandbox são enviados para Produção?

Não.

Clientes, cobranças, assinaturas, configurações, Webhooks e demais recursos criados no Sandbox não são replicados em Produção.

Ao realizar o go-live, será necessário configurar novamente os recursos no ambiente produtivo.

Saldo e movimentações financeiras

5 - Como adicionar saldo à conta Sandbox?

O saldo não é disponibilizado automaticamente.

Para gerar saldo:

1. crie um cliente de teste;
2. crie uma cobrança por Pix ou boleto;
3. confirme manualmente o pagamento;
4. utilize o valor disponibilizado nos demais testes.

Criar cliente
      ↓
Criar cobrança
      ↓
Confirmar o pagamento
      ↓
Adicionar saldo
      ↓
Executar os testes

Consulte Adicione saldo à sua conta Sandbox.

6 - Os pagamentos realizados no Sandbox movimentam dinheiro real?

Não.

As operações são registradas somente para homologação. Nenhum valor real é movimentado e nenhuma instituição financeira é acionada.

7 - Por que uma transferência ou pagamento retorna saldo insuficiente?

Algumas operações exigem saldo disponível, como:

• transferências Pix;
• transferências TED;
• pagamentos de contas;
• antecipações;
• outras movimentações financeiras.

Antes de executar a operação, consulte o saldo da conta e, se necessário, confirme uma cobrança de teste.

Webhooks e notificações

8 - Os Webhooks funcionam no Sandbox?

Sim.

Você pode configurar Webhooks e utilizar os eventos do Sandbox para validar:

• recebimento das notificações;
• atualização dos status internos;
• processamento assíncrono;
• idempotência;
• falhas e reprocessamentos.

9 - Posso testar notificações por e-mail e SMS?

Sim.

Utilize somente e-mails e números de telefone próprios ou autorizados para os testes.

Não cadastre dados reais de terceiros ou contatos aleatórios, pois as notificações podem ser enviadas durante a homologação.

10 - Posso testar notificações por WhatsApp?

Não.

O envio de notificações por WhatsApp não é realizado no Sandbox devido ao custo envolvido na mensageria.

Cartão de crédito

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

Sim.

Utilize os cartões disponibilizados para homologação.

Simular aprovação

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

Simular recusa

Mastercard: 5184019740373151
Visa: 4916561358240741

Utilize somente dados fictícios para o titular do cartão.

Consulte Teste pagamentos com cartão de crédito no Sandbox.

12 - Posso testar tokenização de cartão?

Sim.

A tokenização pode ser habilitada nas configurações da conta Sandbox e utilizada para homologar cobranças futuras sem reenviar os dados do cartão.

A disponibilidade no Sandbox não representa uma habilitação automática em Produção.

Transferências

13 - Posso testar transferências Pix?

Sim, com comportamentos diferentes conforme o destino utilizado.

Chave Pix fictícia de homologação

Permite validar o envio e o débito da transferência. O valor não é creditado em outra conta.

Chave de outra conta Sandbox

Permite validar:

• débito na conta de origem;
• crédito na conta de destino;
• atualização dos saldos;
• conciliação entre as contas.

Consulte Teste transferências no Sandbox.

14 - Posso testar transferências TED?

Sim.

Após criar a TED, utilize os controles disponíveis no Sandbox para:

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

Esses controles são exclusivos do ambiente de homologação.

Pix e QR Codes

15 - Posso testar o pagamento de um QR Code Pix?

Sim, desde que o QR Code seja compatível com os cenários disponíveis no Sandbox.

O fluxo recomendado é:

1. utilizar uma conta Sandbox para criar o QR Code;
2. obter o payload retornado;
3. utilizar outra conta Sandbox, com saldo, para realizar o pagamento;
4. validar o débito, o recebimento, os status e os Webhooks.

Consulte Teste o pagamento de QR Codes Pix.

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

O erro 404 Not Found pode ocorrer quando:

• a conta que gerou o QR Code não possui uma chave Pix cadastrada;
• o payload não foi registrado no Sandbox;
• a cobrança foi criada em um cenário incompatível com esse teste;
• foi utilizado um QR Code criado antes do cadastro da chave Pix.

Para corrigir:

1. cadastre uma chave Pix na conta Sandbox;
2. crie uma nova cobrança ou um novo QR Code;
3. obtenha o novo payload;
4. execute novamente o pagamento.

17 - Posso remover uma chave Pix no Sandbox?

Não.

A remoção de chaves Pix não está disponível para homologação nesse ambiente.

Contas e subcontas

18 - Como funciona a aprovação de uma conta Sandbox?

Contas criadas diretamente no Sandbox são aprovadas automaticamente quando os dados comerciais obrigatórios são preenchidos corretamente.

Para evitar falhas:

• preencha todos os campos obrigatórios;
• utilize valores compatíveis com cada campo;
• utilize apenas letras e espaços no nome;
• evite números e caracteres especiais.

Exemplo que pode impedir a aprovação:

Conta Teste_01

Prefira:

Conta Teste Um

Consulte Aprove contas e subcontas no Sandbox.

19 - Por que o Pix está desabilitado na conta Sandbox?

Isso pode ocorrer quando os dados comerciais não foram validados corretamente.

Revise principalmente:

• campos obrigatórios não preenchidos;
• nome com números;
• nome com caracteres especiais;
• valores incompatíveis com o formato esperado.

Após corrigir os dados, aguarde uma nova validação e consulte novamente o status da conta.

20 - Posso aprovar uma subconta manualmente?

Sim.

Utilize o endpoint:

POST /v3/accounts/{id}/approve

Consulte o endpoint: Aprovar conta no Sandbox.

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

21 - Como funciona o acesso de uma subconta padrão?

No Sandbox, o link de redefinição de senha da subconta padrão é enviado ao e-mail da conta pai responsável pela criação.

Após receber o e-mail:

1. acesse o link;
2. defina a senha da subconta;
3. realize o login com os dados da subconta.

Esse é um comportamento específico do Sandbox e pode ser diferente em Produção.

22 - Posso testar o onboarding de uma subconta BaaS?

Sim, com restrições.

O campo onboardingUrl pode ser utilizado para homologar o preenchimento cadastral e o envio das informações solicitadas.

Entretanto, o Sandbox não reproduz integralmente todas as validações cadastrais, regulatórias e operacionais de Produção.

Segurança

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

É uma validação adicional exigida em determinadas operações sensíveis.

Quando uma ação crítica for solicitada no Sandbox, utilize:

000000

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

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

Em cenários específicos de transferências, a validação pode ser desabilitada no Sandbox pelo time de Sucesso de Integrações.

Homologue primeiro o fluxo com o token habilitado. A desabilitação não representa a configuração recomendada para Produção.

Consulte Entre em contato.

Assinaturas

25 - Posso gerar antecipadamente as cobranças de uma assinatura?

Sim.

Utilize a geração de carnê para criar as cobranças futuras da assinatura até uma data final definida.

Esse recurso permite testar:

• consultas de cobranças;
• recorrências;
• relatórios;
• conciliações;
• sincronizações;
• eventos aplicáveis às cobranças geradas.

A geração do carnê cria as cobranças, mas não realiza o pagamento delas.

Consulte Gerar carnê de assinatura.

Disponibilidade das funcionalidades

26 - Todas as funcionalidades podem ser testadas no Sandbox?

Não.

As funcionalidades podem ser classificadas como:

Exemplos de funcionalidades com restrições:

• transferências Pix;
• pagamento de QR Code Pix;
• teste de chargeback;
• envio de documentos no onboarding BaaS.

Exemplos de funcionalidades indisponíveis:

• remoção de chave Pix;
• simulação de antecipação;
• notificações por WhatsApp;
• layout de boleto com QR Code Pix;
• alguns recursos dependentes de serviços externos.

Consulte: Veja o que pode ser testado no Sandbox.

Solução de problemas

27 - Quais são os erros mais comuns no Sandbox?

• Chave de API incorreta: Ocorre quando a chave pertence a outro ambiente ou conta.

• URL incorreta: Ocorre quando uma chave de Sandbox é enviada para Produção ou o contrário.

• Saldo insuficiente: corre quando a operação exige recursos disponíveis e a conta ainda não possui saldo de teste.

• Webhook não recebido: Pode estar relacionado à URL configurada, autenticação, indisponibilidade do servidor ou resposta diferente de 200.

• Pix desabilitado: Pode estar relacionado a dados comerciais inválidos ou incompletos.

• Erro 404 no pagamento de QR Code Pix: Pode ocorrer quando a conta não possui chave Pix ou quando o payload não foi registrado no Sandbox.

O que devo validar antes de ir para Produção?

Confirme se:

• os fluxos de sucesso e erro foram homologados;
• os Webhooks são processados de forma idempotente;
• a URL foi alterada para Produção;
• a chave de API pertence ao ambiente produtivo;
• os dados fictícios foram removidos;
• os recursos necessários estão habilitados;
• as permissões da chave estão corretas;
• as diferenças entre Sandbox e Produção foram consideradas;
• os requisitos cadastrais, regulatórios e operacionais foram validados.

Conteúdos relacionados

• Conheça o Sandbox
• Configure sua conta no Sandbox
• Adicione saldo à conta Sandbox
• Teste funcionalidades no Sandbox
• Veja o que pode ser testado
• Aprove contas e subcontas
• Conheça os Webhooks
• Crie e gerencie chaves de API