Simulação

Use a simulação para testar pagamentos Pix e boleto, estornos e resultados que aguardam confirmação. Os resultados alteram os registros do Sandbox para que você possa conferir o acompanhamento da cobrança e os efeitos no saldo, extrato e comprovantes.

Usar somente no Sandbox

Crie o cliente e a cobrança com uma chave de API de Sandbox da sua empresa. Use essa mesma empresa e ambiente para simular o resultado e consultar os registros. A chave identifica o ambiente; você não informa o ambiente no corpo ou na URL da requisição.

Informe o identificador da cobrança ou do estorno no caminho, conforme a requisição. Uma chave de Produção recebe 403 SANDBOX_ENVIRONMENT_REQUIRED. Um ID inexistente, de outra empresa ou de outro ambiente recebe a mesma resposta de recurso não encontrado.

Confirmar um pagamento

Use Confirmar pagamento para concluir o pagamento de uma cobrança de teste que ainda esteja aberta. A resposta informa status: 4, correspondente a paga, e amount_cents com o valor da cobrança em centavos de real.

O valor é creditado no saldo do Sandbox uma única vez. Você pode conferir o saldo em Consultar saldo e acompanhar o lançamento em Extrato. O lançamento pode levar alguns instantes para aparecer; não repita a confirmação para tentar acelerar essa atualização.

Para testar os dados de pagamento e o recibo, crie a cobrança com o meio desejado: payment_method: 1 para Pix ou payment_method: 2 para boleto. Consulte as condições de emissão em Cobranças. Depois da confirmação, use as consultas de dados do pagamento e recibo. Os documentos de teste identificam o pagamento como simulado. A confirmação não escolhe um meio de pagamento para a cobrança.

Simular uma falha

Use Simular falha no pagamento para testar o tratamento de uma cobrança aberta que não foi paga. A resposta informa status: 9, correspondente a falha. Esse resultado não credita saldo nem gera um recebimento no extrato.

A falha encerra esse teste. Para conferir um pagamento aprovado depois disso, crie outra cobrança de Sandbox.

Estorno Pix pendente e com falha

Crie uma cobrança Pix, confirme o pagamento e use Simular estorno pendente. Envie o valor em amount_cents, como no pedido normal de estorno. As condições de saldo e valor restante continuam valendo.

A resposta 202 retorna o ID do estorno com status: accepted. Guarde esse ID para acompanhar a solicitação. O valor solicitado sai do saldo total e disponível enquanto o pedido aguarda resultado; essa reserva não aumenta o campo de saldo bloqueado. O comprovante ainda não está disponível.

Escolha um resultado para o mesmo estorno:

• Concluir estorno simulado retorna completed, atualiza a devolução na cobrança e permite consultar o comprovante. O valor não é descontado novamente.
• Simular falha no estorno retorna failed, com REFUND_PROCESSING_FAILED em failure_reason.code, e devolve o valor ao saldo disponível. Não há comprovante de devolução concluída.

Repetir o mesmo resultado final retorna o estorno sem repetir seu efeito. Tentar trocar um resultado concluído por falha, ou uma falha por conclusão, retorna 409 REFUND_NOT_SIMULATABLE. Para outro teste, confira a elegibilidade antes de criar uma nova solicitação. Repetir a criação de um pedido enquanto houver outro pendente recebe PIX_REFUND_IN_PROGRESS; use o ID já recebido para concluir ou falhar esse pedido.

O endpoint normal POST /v1/charges/{id}/refunds continua concluindo a devolução imediatamente no Sandbox. Use as rotas de simulação quando precisar testar a espera e o resultado posterior.

Compensação e liquidação do boleto

Crie uma cobrança de boleto e emita as instruções de pagamento. Use Simular compensação de boleto para registrar que o pagamento foi compensado, mas ainda aguarda liquidação. Essa etapa não credita o saldo nem disponibiliza um comprovante de pagamento concluído.

A consulta da cobrança informa o andamento em payment_information.boleto_payment_status: awaiting_payment antes da compensação, compensated enquanto aguarda liquidação e settled depois da confirmação. Sem andamento disponível, o campo retorna null.

Depois, use Confirmar pagamento para liquidar o boleto. Só essa confirmação credita o valor e permite consultar os dados do pagamento e o recibo. O extrato pode levar alguns instantes para mostrar o recebimento. Repetir a compensação ou a confirmação não repete o crédito.

Emissão e cancelamento com pendência ou falha

Use Preparar cenário antes da ação que deseja testar. Envie action com pix_issuance, boleto_issuance ou cancellation e escolha outcome: pending ou outcome: failed. A resposta com state: configured confirma a preparação; ela ainda não emitiu nem cancelou a cobrança.

Para emissão, crie a cobrança com payment_method_types: [1] para Pix ou payment_method_types: [2] para boleto, sem emissão na criação. Prepare o cenário e use Emitir pagamento de teste, informando payment_method: 1 ou 2. A emissão pelo checkout da cobrança também usa o cenário preparado. Consulte as condições de cadastro em Cobranças.

Para cancelamento, prepare o cenário antes de usar Revogar cobrança. A requisição normal apresenta o resultado pendente ou a falha escolhida. Preparar o cenário não altera o saldo e não devolve um pagamento já recebido.

Com outcome: pending, acompanhe a cobrança e use Resolver cenário pendente para escolher completed ou failed para a mesma action. Essa requisição conclui uma ação que já começou; não inicia a emissão nem o cancelamento. Uma emissão concluída disponibiliza o Pix ou boleto, sem confirmar pagamento. Um cancelamento concluído revoga a cobrança, sem estornar valores.

Com outcome: failed, a ação apresenta a falha sem passar pela etapa de resolução. A falha de emissão fica em pix_status ou boleto_status e seu motivo em pix_error ou boleto_error. Ela é diferente de Simular falha no pagamento, que encerra a cobrança com falha de pagamento.

Cada cenário vale para a cobrança informada. Repetir a mesma preparação ou resolução preserva o resultado; tentar substituir um cenário já definido recebe 409 CHARGE_SCENARIO_CONFLICT. Crie outra cobrança para testar uma combinação diferente.

Repetir uma simulação

Se a conexão for interrompida, consulte a cobrança ou o estorno pelo mesmo ID. Repetir uma confirmação, falha de pagamento, compensação ou etapa de cenário já aplicada informa duplicate: true, sem aplicar novamente o efeito financeiro. Nas conclusões e falhas de estorno, a resposta apresenta o mesmo estorno com seu estado final.

Uma cobrança já paga não pode receber uma falha de pagamento simulada, e uma cobrança com falha não pode receber uma confirmação. Essas duas requisições também recusam cobranças canceladas ou com outro resultado encerrado, com 409 CHARGE_NOT_SIMULATABLE. Consulte o estado atual e crie outra cobrança para testar um resultado diferente.

Testar os demais recursos

Use os endpoints de cada recurso com a chave Sandbox. Não é necessário um endpoint de simulação para criar clientes, criar ou atualizar cobranças, gerenciar links de pagamento ou revogar uma cobrança.

Para testar uma devolução, crie uma cobrança Pix, confirme seu pagamento e use Estornos. As condições de saldo, valor restante e estado da cobrança continuam valendo. A devolução no Sandbox é simulada; o endpoint de estorno não recebe boleto.

As consultas de saldo, extrato, estatísticas, dados de pagamento e comprovantes permitem conferir os resultados de teste. A solicitação de saque continua restrita a Produção; as simulações de cobrança não transferem valores para uma conta bancária.

Para testar uma cobrança vencida, crie-a com um prazo curto e aguarde o vencimento. A simulação de pagamento também pode confirmar uma cobrança cujo prazo passou, desde que ela continue aberta para receber o resultado. A simulação preserva a data de vencimento da cobrança.

As consultas de Contestações retornam os casos disponíveis no ambiente consultado. Confirmar um pagamento de teste não abre uma contestação.

As mudanças confirmadas pela simulação geram os eventos de webhook correspondentes para os destinos cadastrados no Sandbox. As requisições ao seu endpoint são reais; use um receptor de testes e consulte Receber e validar eventos. Requisições de outros recursos que solicitam envio de e-mail mantêm suas próprias regras; use somente destinatários autorizados nos testes.