Aprovação de contas

Mesmo sendo muito semelhante ao ambiente de produção, o ambiente de Sandbox requer alguns cuidados para que a aprovação de contas e subcontas seja realizada corretamente.

Aprovação de contas avulsas

No Sandbox, a conta é aprovada automaticamente no momento da criação, desde que todos os dados comerciais obrigatórios sejam preenchidos corretamente.

Garanta que os dados informados sejam condizentes com o tipo do campo, como por exemplo evitar o uso de números no campo de Nome.

Após o envio das informações solicitadas no cadastro, a validação ocorre de forma automática, sem necessidade de envio manual de documentos.

No ambiente de teste, os dados informados não precisam ser reais. É obrigatório apenas o preenchimento completo dos campos exigidos para que a validação seja concluída.

👍
Dica
Caso não queira usar dados reais, utilize ferramentas que geram dados fictícios de empresas ou pessoas para realizar seus testes, como por exemplo: https://geradorbr.com/gerador-de-pessoas/

❗
Importante
O uso de números ou caracteres especiais (como _, #, !, -, entre outros) pode:

Impedir a validação automática da conta
Desativar o PIX
Comprometer o funcionamento correto da integração

Evite:

Conta Teste_01

Prefira:

Conta Teste Um

Se a conta não for aprovada automaticamente ou o PIX aparecer como desabilitado, revise o nome cadastrado, remova números e caracteres especiais e atualize as informações.

Caso o problema persista, entre em contato com o suporte.

Subcontas

No ambiente de Sandbox, a aprovação de subcontas pode ser realizada por meio do endpoint de aprovação de contas ou utilizando o fluxo de autoaprovação descrito aqui.

É fundamental garantir o preenchimento correto de todos os dados comerciais obrigatórios no momento da criação da subconta.

Além disso, deve-se manter o mesmo cuidado com o nome da subconta, utilizando apenas letras e espaços.

Cada modelo de subconta possui comportamentos específicos no ambiente de teste, conforme descrito abaixo.

Subcontas padrão

Ao criar uma subconta padrão no Sandbox, o link de redefinição de senha é enviado para o e-mail da conta pai.

Para acessar a subconta, é necessário:

Acessar o link recebido
Definir a senha da subconta
Realizar o login normalmente

Subcontas White Label

No modelo White Label, o onboarding deve ser realizado por meio do onboardingUrl, onde o usuário final efetua o envio dos documentos obrigatórios.

No ambiente de Sandbox, esse link possui caráter apenas ilustrativo, não representando o fluxo completo e real de validação que ocorre em produção.

Atualização de dados comerciais

Ao atualizar dados comerciais da conta ou subconta no Sandbox, algumas informações podem ser preenchidas automaticamente durante o processo de validação.

Por exemplo, o Asaas pode inserir um nome padrão, como "João da Silva", para permitir a finalização das atualizações no ambiente de teste.

Da mesma forma, ao acessar a aba Meu usuário, você pode visualizar informações como CPF, endereço ou data de nascimento que não reconhece.

Esses dados são simulados e utilizados exclusivamente para o funcionamento interno do ambiente Sandbox, não representando dados reais.

Para suporte, entre em contato com: [email protected]

Erros comuns e boas práticas

Durante a homologação em Sandbox, alguns problemas são recorrentes. Antes de acionar o suporte, revise os pontos abaixo.

Utilizar a API Key ou a URL do ambiente errado

Verifique se a API Key utilizada corresponde ao ambiente correto.

API Key de Sandbox deve ser usada com https://api-sandbox.asaas.com/
API Key de produção deve ser usada com https://api.asaas.com/

Misturar credencial e ambiente é uma das causas mais comuns de erro de autenticação ou comportamento inesperado.

Tentar testar operações sem saldo disponível

Alguns fluxos exigem saldo na conta Sandbox. Nesses casos, crie e confirme cobranças fictícias antes de iniciar o teste.

Esperar comportamento idêntico ao ambiente de produção

Embora o Sandbox replique grande parte da jornada real, algumas etapas possuem comportamento específico de homologação, como:

aprovações automáticas
confirmações manuais
uso de dados simulados
controles de teste disponíveis apenas nesse ambiente

Utilizar dados inválidos no cadastro da conta

Nomes com números, caracteres especiais ou preenchimentos inconsistentes podem impedir a aprovação automática da conta e comprometer o funcionamento do Pix em Sandbox.

Testar notificações com dados de terceiros

As notificações por e-mail e SMS funcionam normalmente no Sandbox. Para evitar disparos indevidos, utilize somente seus próprios contatos para testes.

Ignorar restrições específicas da funcionalidade

Antes de considerar um fluxo como homologado, verifique se ele possui suporte completo no Sandbox ou se existe alguma limitação documentada neste guia.

Antes de ir para produção

Antes de trocar sua integração para produção, revise se:

a URL da API foi alterada para o ambiente correto
a API Key utilizada é a de produção
os recursos necessários estão habilitados em conta real
o fluxo completo foi validado em Sandbox
sua aplicação trata corretamente respostas, falhas e webhooks
as limitações do Sandbox foram consideradas na homologação

O fato de um fluxo funcionar no ambiente de testes não significa, por si só, que todos os requisitos de produção já estejam atendidos. Por isso, a validação final deve considerar permissões, habilitações e o comportamento real do ambiente produtivo.

Próximos passos

Depois de configurar sua conta Sandbox, recomendamos seguir esta ordem:

gerar sua API Key de Sandbox
apontar sua integração para a URL de Sandbox
criar um cliente fictício
emitir uma cobrança de teste
confirmar o pagamento para simular saldo
testar os fluxos específicos da sua integração
validar o recebimento de webhooks
revisar as limitações do ambiente antes do go-live
trocar a integração para produção somente após a homologação completa