Testando no Sandbox

Use o Sandbox para validar a criação de pagamentos de contas, o tratamento das respostas da API e o recebimento de Webhooks sem movimentar valores reais.

Antes de começar

Você precisa:

• utilizar uma conta e uma chave de API do Sandbox;
• possuir saldo disponível para realizar o pagamento;
• criar uma cobrança por boleto na mesma conta Sandbox;
• obter a linha digitável dessa cobrança.

Se precisar gerar saldo para o teste, consulte Adicionando saldo em uma conta Sandbox.

Como testar

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["Preparar saldo no Sandbox"] --> B["Criar cobrança por boleto"]
    B --> C["Obter a linha digitável"]
    C --> D["Criar o pagamento de conta"]
    D --> E["Armazenar o ID"]
    E --> F["Receber os Webhooks"]
    F --> G["Validar o tratamento da integração"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px

    class A inicio
    class B,C,D,E,F validacao
    class G sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

1. Crie um boleto no Sandbox

Crie uma cobrança com billingType igual a BOLETO na mesma conta Sandbox utilizada para testar o Pague Contas.

Depois, obtenha a linha digitável da cobrança.

• Criar nova cobrança
• Obter linha digitável do boleto

2. Crie o pagamento de conta

Envie a linha digitável no campo identificationField para:

POST /v3/bill

Exemplo:

{
  "identificationField": "34191090570404959480975279260006611980000081488",
  "externalReference": "teste-sandbox-001"
}

Substitua identificationField pela linha digitável do boleto criado na sua própria conta Sandbox.

Consulte o endpoint Criar um pagamento de conta.

3. Valide o processamento por Webhook

Armazene o ID retornado na criação e utilize os Webhooks de Pague Contas para validar as alterações da operação.

No Sandbox, o pagamento não passa por compensação bancária real. Por isso, o status final FAILED após a criação é esperado nesse ambiente.

Ao receber BILL_FAILED, valide se sua aplicação:

• identifica a operação por bill.id;
• atualiza o status corretamente;
• interpreta bill.failReasons;
• trata o evento de forma idempotente.

Não utilize consultas periódicas à API como mecanismo principal para acompanhar alterações de status.

Consulte os eventos para Pague Contas.

Como validar o teste

Considere o fluxo homologado quando sua aplicação conseguir:

• criar o pagamento e armazenar seu ID;
• receber e processar os Webhooks;
• atualizar o estado interno da operação;
• tratar o FAILED esperado no Sandbox sem interpretá-lo como compensação bancária real.

O comportamento do Sandbox valida a integração técnica, mas não representa a compensação de um boleto em Produção.

Se o pagamento não for criado

Verifique se:

• o boleto foi criado no Sandbox;
• a linha digitável pertence ao boleto utilizado no teste;
• a conta possui saldo disponível;
• a requisição utiliza https://api-sandbox.asaas.com/v3;
• a chave de API pertence ao Sandbox.

Para outros retornos, consulte Erros e exceções comuns — Pague Contas.

Próximos passos

• Consulte os status do Pague Contas
• Configure o tratamento dos eventos por Webhook
• Consulte os erros e exceções comuns
• Consulte o endpoint Criar um pagamento de conta