Sandbox

Esta página reúne dúvidas frequentes sobre o ambiente Sandbox do Asaas, com foco em criação de conta, saldo fictício, funcionalidades disponíveis para teste e pagamento de QR Code Pix.

O Sandbox é um ambiente de testes separado do ambiente de Produção. Ele permite validar fluxos da integração sem movimentar valores reais, oferecendo mais segurança antes da entrada em produção.

Quando utilizar este FAQ

Utilize esta página quando precisar esclarecer dúvidas sobre:

• criação de conta Sandbox;
• adição de saldo fictício;
• simulação de pagamentos;
• teste de pagamento de QR Code Pix;
• funcionalidades disponíveis no ambiente de testes;
• limitações do Sandbox;
• diferenças entre Sandbox e Produção;
• boas práticas de homologação.

1. Como crio minha conta em Sandbox?

O Sandbox é um ambiente de testes onde você pode receber cobranças fictícias e testar integrações e Webhooks antes de utilizar o ambiente de Produção.

Você pode criar sua conta Sandbox em:

https://sandbox.asaas.com/

2. Quais funcionalidades posso testar na minha conta Sandbox?

No ambiente Sandbox, você pode testar diversos fluxos da integração, como:

• criação e atualização de clientes;
• criação de cobranças;
• cobranças por boleto;
• cobranças por Pix;
• cobranças por cartão de crédito;
• cobranças parceladas;
• split de pagamento;
• transferências;
• movimentações;
• Webhooks;
• fluxos de consulta e atualização de recursos.

Para consultar a lista completa e atualizada de funcionalidades disponíveis para teste, acesse a documentação O que pode ser testado.

3. Como posso adicionar saldo em minha conta Sandbox?

Em Sandbox, é possível adicionar saldo fictício à conta para realizar testes.

Uma forma comum de fazer isso é criar clientes fictícios e cobranças fictícias. Após criar uma cobrança com pagamento via Boleto ou Pix, será exibido um botão de CONFIRMAR PAGAMENTO, permitindo simular o recebimento daquela cobrança.

Se a cobrança for de Cartão de Crédito e estiver com status CONFIRMADA, será exibido o botão RECEBER PAGAMENTO.

Fluxo recomendado:

Criar cliente fictício
↓
Criar cobrança fictícia
↓
Acessar a cobrança no Sandbox
↓
Confirmar ou receber o pagamento pela interface
↓
Validar o saldo fictício
↓
Testar o fluxo desejado

4. É possível confirmar pagamento via API no Sandbox?

Não.

No momento, não existe um endpoint específico para confirmação de pagamento via API no Sandbox.

Para simular o recebimento de cobranças, utilize os botões disponíveis na interface do Sandbox, como CONFIRMAR PAGAMENTO ou RECEBER PAGAMENTO, conforme o tipo e o status da cobrança.

5. Como testar a funcionalidade de pagar QR Code Pix no Sandbox?

Para testar o pagamento de QR Code Pix no Sandbox, primeiro crie um QR Code Pix estático na sua conta Asaas.

Você pode utilizar a referência Criar QR Code estático:

Criar QR Code estático

Ao criar o QR Code estático, a resposta retornará o payload. Esse valor representa o conteúdo Pix Copia e Cola do QR Code e será utilizado na chamada de pagamento.

Depois disso, copie o payload retornado e envie essa informação na chamada Pagar um QR Code:

Pagar um QR Code

Fluxo resumido:

Criar QR Code Pix estático
↓
Copiar o payload retornado
↓
Enviar o payload na chamada de Pagar um QR Code
↓
Validar o resultado do pagamento
↓
Acompanhar atualização da integração

6. Quais campos são importantes para pagar um QR Code Pix?

Na chamada de pagamento de QR Code Pix, os principais campos são:

7. Exemplo de criação de QR Code estático

A criação do QR Code estático deve ser feita no ambiente Sandbox.

Exemplo ilustrativo de requisição:

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

Alguns campos importantes na criação do QR Code estático são:

8. Exemplo de pagamento de QR Code Pix

Após criar o QR Code estático e obter o payload, utilize a chamada de pagamento.

Exemplo ilustrativo:

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

9. O que acontece depois que eu pago um QR Code Pix no Sandbox?

Ao realizar o pagamento de um QR Code Pix no Sandbox:

• o pagamento é processado no ambiente de testes;
• uma cobrança Pix pode ser criada automaticamente;
• os identificadores relacionados ao Pix são vinculados à cobrança;
• sua integração pode receber eventos de Webhook, conforme a configuração realizada;
• sua aplicação pode validar atualizações de status e conciliação interna.

Esse fluxo é útil para validar se a aplicação está preparada para tratar o recebimento Pix e os eventos gerados pelo Asaas.

10. Quais erros podem ocorrer ao testar pagamento de QR Code Pix?

Alguns erros comuns incluem:

11. O saldo adicionado no Sandbox é real?

Não.

O saldo exibido no Sandbox é fictício e serve apenas para testes de integração.

Nenhuma cobrança, transferência, pagamento ou movimentação realizada no Sandbox gera impacto financeiro real.

12. Posso usar a mesma API Key em Sandbox e Produção?

Não.

Cada ambiente possui sua própria API Key.

A API Key gerada no Sandbox funciona apenas no Sandbox. A API Key gerada em Produção funciona apenas no ambiente de Produção.

13. Os Webhooks funcionam no Sandbox?

Sim.

O Sandbox permite testar Webhooks para validar se sua aplicação está recebendo e processando corretamente os eventos enviados pelo Asaas.

Esse teste é importante para confirmar se sua integração atualiza pedidos, cobranças, status internos e demais fluxos assíncronos conforme esperado.

14. Quando devo migrar minha integração para Produção?

Migre para Produção somente após validar os principais fluxos da sua integração no Sandbox.

Antes da migração, confirme se:

• os clientes são criados corretamente;
• as cobranças são geradas com os dados esperados;
• os pagamentos de teste foram simulados;
• o saldo fictício foi suficiente para validar os fluxos necessários;
• os Webhooks foram recebidos e processados corretamente;
• sua aplicação atualiza os status internos conforme esperado;
• os erros comuns foram tratados pela integração;
• a API Key de Produção foi configurada no ambiente correto.

15. O que devo fazer se uma funcionalidade não estiver disponível no Sandbox?

Caso uma funcionalidade não esteja disponível para teste no Sandbox, consulte a documentação O que pode ser testado para confirmar se existe alguma limitação conhecida.

Se o recurso for essencial para a homologação da sua integração, entre em contato com o time de Sucesso de Integrações para avaliar o cenário.

Boas práticas

Conteúdos relacionados

Consulte também:

• O que pode ser testado;
• Criar QR Code estático;
• Pagar um QR Code;
• Testar pagamento de QR Code Pix;
• Como configurar sua conta no Sandbox;
• Como testar funcionalidades em Sandbox;
• Webhooks;
• Testando transferências;
• Como testar ações críticas.