Skip to main content
POST
Esta rota existe só para testes. Ela pega uma cobrança criada com a chave de teste e dispara um evento novo, charge.{status}, com o status que você escolher. Assim você testa como o seu sistema reage a um pagamento confirmado, a uma recusa ou a um estorno sem esperar o evento real acontecer.
Apesar do nome da rota, ela não reenvia o evento original. Ela gera um evento simulado, com id novo, e não altera a cobrança: depois da chamada, GET /v1/charges/{id} continua mostrando o status real.

Quando usar

Para o negócio: esta rota acelera a homologação. O time técnico simula cada situação e comprova que o sistema libera, cancela ou bloqueia pedidos do jeito certo. O cenário CHG-09 do roteiro de homologação pede essa evidência.

Antes de chamar

  • Use a chave de teste (sk_test_) (Credenciais e ambientes).
  • Tenha uma cobrança criada com essa chave de teste. Cobranças de produção recebem 403.
  • Tenha um destino para o evento: um endpoint de webhook cadastrado na conta ou a postbackUrl informada na cobrança.

Parâmetros de caminho

string
required
ID da cobrança de teste. Ex.: 2vorkDcXyvzifL63YX09S9VqcnI.

Corpo da requisição

string
required
Status simulado. Define o evento enviado (paid gera charge.paid, refunded gera charge.refunded e assim por diante). Valores aceitos: paid, pending, refused, failed, refunded, in_analysis e authentication_required. pre_chargeback e chargeback não são aceitos e recebem 400.

O que é enviado

  • Um evento charge.{status} novo, no envelope padrão, com id de evento novo e livemode: false.
  • Destinos: a postbackUrl da cobrança, se houver, e os endpoints de webhook da própria conta.
  • O payload simulado não é idêntico ao real: traz campos a mais e não traz anticipation_fee_estimated. Use esta rota para testar conectividade e o tratamento de cada evento. O formato de referência está em Webhooks de cobrança.

Respostas

A resposta 201 traz o resultado da entrega em cada destino.
object[]
Uma entrada por destino notificado.
Para o desenvolvedor: o 201 confirma que a Finvia disparou o evento. Leia deliveries para saber se cada destino aceitou: success: false com error indica problema no seu endpoint. Para a evidência de homologação, guarde a resposta desta rota e o log do evento recebido.

Roteiro de teste sugerido

1

Crie uma cobrança de teste

Crie uma cobrança com a chave sk_test_ em POST /v1/charges e guarde o id.
2

Simule a recusa

Chame esta rota com {"status": "refused"} e confira se o seu sistema não liberou o pedido.
3

Simule o pagamento

Chame com {"status": "paid"} e confira se o seu sistema consultou a cobrança antes de liberar.
4

Simule o estorno

Chame com {"status": "refunded"} e confira se o pedido foi cancelado.
5

Repita um evento

Chame duas vezes com o mesmo status e confira se o pedido não foi processado em dobro.
O teste está completo quando, para cada status simulado, deliveries mostra success: true e o pedido mudou para a situação esperada no seu sistema.
Como o evento simulado não altera a cobrança, um handler que confirma o status com GET /v1/charges/{id} antes de agir vai ver o status real da cobrança. Isso é o comportamento correto em produção. Para testar o caminho completo de um Pix pago, crie uma cobrança Pix com a chave de teste: ela é confirmada sozinha cerca de 5 segundos depois.

Erros comuns

Como testar

Este endpoint cobre o cenário CHG-09 (simulação de webhook no sandbox) e apoia o CHG-08 (recebimento de webhook) do Roteiro de homologação.

Veja também

Webhooks de cobrança

Eventos e payloads reais de cobrança.

Visão geral de webhooks

Como cadastrar e tratar webhooks.

Criar uma cobrança

Gere a cobrança de teste.

Roteiro de homologação

Cenários CHG-08 e CHG-09.