Adicionando saldo em uma conta Sandbox

Em Sandbox, é possível simular saldo na conta para validar fluxos que dependem de movimentação financeira, como transferências, pagamentos, antecipações, saques e outras operações que exigem saldo disponível.

Como o ambiente Sandbox não processa movimentações financeiras reais, o saldo precisa ser gerado artificialmente para permitir a execução desses testes.

Quando utilizar

A simulação de saldo é recomendada quando sua integração precisa testar funcionalidades que dependem de recursos financeiros disponíveis na conta, como:

• Transferências Pix.
• Transferências entre contas Asaas.
• Pagamentos de cobranças.
• Antecipações.
• Consultas de saldo.
• Fluxos financeiros personalizados.

Sem saldo disponível, algumas dessas operações podem retornar erros relacionados à insuficiência de recursos.

Fluxo recomendado

O processo mais comum para adicionar saldo em uma conta Sandbox consiste em:

1. Criar um cliente fictício.
2. Criar uma cobrança utilizando boleto ou Pix como forma de pagamento.
3. Confirmar manualmente o recebimento da cobrança.
4. Utilizar o valor recebido como saldo disponível para os testes.

Fluxo simplificado:

Criar cliente
        ↓
Criar cobrança
(Boleto ou Pix)
        ↓
Confirmar pagamento
        ↓
Saldo disponibilizado
na conta Sandbox
        ↓
Executar testes financeiros

Criando os recursos necessários

Antes de adicionar saldo, é necessário possuir:

Cliente

A cobrança deve estar vinculada a um cliente previamente cadastrado.

Os campos mínimos normalmente utilizados são:

• name
• cpfCnpj

Consulte também:

• Criar cliente

Cobrança

Após criar o cliente, crie uma cobrança utilizando uma das formas de pagamento compatíveis com confirmação em Sandbox:

• BOLETO
• PIX

Após a criação da cobrança, ela ficará disponível para confirmação.

Confirmando o pagamento

Ao criar uma cobrança com pagamento via boleto ou Pix, um botão fica disponível na interface para confirmar o pagamento daquela cobrança.

Após a confirmação, o valor da cobrança passa a compor o saldo disponível da conta Sandbox.

Esse saldo poderá ser utilizado em testes subsequentes normalmente.

Comportamento da confirmação

A confirmação realizada em Sandbox possui finalidade exclusivamente de teste.

Ao confirmar o pagamento:

• Nenhuma transação financeira real é executada.
• Nenhuma instituição financeira é acionada.
• Nenhum valor é movimentado fora do ambiente Sandbox.
• O recebimento é registrado apenas para simulação da operação.

O saldo costuma ser disponibilizado imediatamente após a confirmação.

📘

Exemplo prático

Uma integração que precisa testar uma transferência Pix pode:

1. Criar um cliente fictício.
2. Gerar uma cobrança Pix de R$ 500,00.
3. Confirmar o pagamento da cobrança.
4. Utilizar os R$ 500,00 simulados para executar a transferência desejada.

Boas práticas

• Utilize clientes e documentos fictícios durante os testes.
• Gere apenas o saldo necessário para validar o cenário desejado.
• Recrie o fluxo completo sempre que precisar validar jornadas de recebimento.
• Valide o comportamento da sua integração após a confirmação do pagamento, simulando o fluxo que ocorreria em produção.

🚧

Confirmação em contas BaaS

Também existe um endpoint específico para confirmação de pagamento via API em cenários de Sandbox.

Consulte a referência em Ações em Sandbox, onde estão disponíveis as chamadas para:

• confirmar o pagamento
• forçar o vencimento de uma cobrança

Possíveis dificuldades

Caso o botão de confirmação não esteja disponível, verifique:

• Se a cobrança foi criada em ambiente Sandbox.
• Se a forma de pagamento utilizada é compatível com confirmação manual.
• Se a cobrança ainda não foi confirmada anteriormente.
• Se a cobrança permanece em um status elegível para confirmação.

Próximos passos

Após adicionar saldo em Sandbox, você pode testar:

• Transferências Pix.
• Transferências entre contas Asaas.
• Antecipações.
• Consultas de saldo.
• Extrato financeiro.
• Fluxos financeiros personalizados.