> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reenviar webhook de teste

> No Modo Teste, dispara um evento novo de uma cobrança de teste com o status que você escolher, para testar o seu tratamento de webhooks.

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.

> [!NOTE]
>
> 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

| Situação | Como usar esta rota |
| - | - |
| Testar a liberação do pedido após pagamento | Envie `status` `paid` |
| Testar o cancelamento após estorno | Envie `status` `refunded` |
| Testar o tratamento de recusa ou falha | Envie `refused` ou `failed` |
| Testar um Pix que fica aguardando | Envie `pending` (no sandbox o Pix real é sempre confirmado) |
| Validar a conectividade do endpoint antes de ir para produção | Envie qualquer status e confira `deliveries` na resposta |
| Cobrança de produção | Não funciona. A rota aceita só cobranças de teste |

> [!NOTE]
>
> **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](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)).
* 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

**id** `string` *required*

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

## Corpo da requisição

**status** `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](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md).

## Respostas

A resposta `201` traz o resultado da entrega em cada destino.

**deliveries** `object[]`

Uma entrada por destino notificado.

**propriedades**

**url** `string`

Endereço notificado.

**status** `integer`

Código HTTP que o destino respondeu.

**success** `boolean`

`true` quando a entrega foi aceita (resposta 2xx).

**error** `string`

Descrição da falha. Opcional: vem só quando a entrega falhou.

| HTTP | Significado | `message` |
| - | - | - |
| `201` | Evento disparado | Corpo com `deliveries` |
| `400` | `status` fora da lista aceita | Lista de mensagens de validação |
| `401` | Credencial inválida | `Unauthorized` |
| `403` | A cobrança não é de teste, ou o perfil do usuário dono da chave não tem permissão | `Redisparo de webhook disponível apenas para cobranças de teste` ou `Acesso negado` |
| `404` | Cobrança não encontrada | `Cobrança não encontrada` |

> [!TIP]
>
> **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`](https://docs.fastpaybrasil.com/referencia/cobrancas/criar) 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.

> [!TIP]
>
> 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.

> [!WARNING]
>
> 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

| Sintoma | Causa | Como resolver |
| - | - | - |
| `403` com `Redisparo de webhook disponível apenas para cobranças de teste` | A cobrança foi criada com a chave de produção | Crie a cobrança com a chave `sk_test_` |
| `400` ao simular `pre_chargeback` ou `chargeback` | Esses status não são aceitos nesta rota | Teste o tratamento com os payloads de exemplo do [guia de bloqueio](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md) |
| Nenhum evento chega ao seu sistema | Nenhum endpoint cadastrado na conta e cobrança sem `postbackUrl` | Cadastre um endpoint no painel ou crie a cobrança com `postbackUrl` |
| `success: false` em `deliveries` | O seu endpoint não respondeu 2xx | Leia `error` e confira se o endpoint está acessível pela internet |

## 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](https://docs.fastpaybrasil.com/homologacao/roteiro.md).

```http REST (JSON) theme={null}
POST /v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
Content-Type: application/json

{
  "status": "paid"
}
```

```bash cURL theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paid" }'
```

```javascript Node.js theme={null}
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

const response = await fetch(
  'https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook',
  {
    method: 'POST',
    headers: {
      Authorization: `Basic ${credentials}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ status: 'paid' }),
  },
);

const { deliveries } = await response.json();
for (const d of deliveries) {
  console.log(d.url, d.success ? 'entregue' : `falhou: ${d.error}`);
}
```

```python Python theme={null}
import os

import requests

payload = {
    "status": "paid",
}

response = requests.request(
    "POST",
    "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    json=payload,
    timeout=30,
)

print(response.status_code)
if response.content:
    print(response.json())
```

```php PHP theme={null}
<?php

$payload = [
    'status' => 'paid',
];

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status, PHP_EOL;
print_r(json_decode($body, true));
```

```java Java theme={null}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

public class Exemplo {
    public static void main(String[] args) throws Exception {
        String credentials = Base64.getEncoder()
            .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());

        String payload = """
            {
              "status": "paid"
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook"))
            .header("Authorization", "Basic " + credentials)
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(payload))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}
```

```csharp C# theme={null}
using System.Net.Http.Headers;
using System.Text;

var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY");
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:"));

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

var payload = """
{
  "status": "paid"
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook");
request.Content = new StringContent(payload, Encoding.UTF8, "application/json");

var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	payload := strings.NewReader(`{
	  "status": "paid"
	}`)

	req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook", payload)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode)
	fmt.Println(string(body))
}
```

```ruby Ruby theme={null}
require "json"
require "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "status" => "paid",
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.code
puts response.body
```

```json 201 theme={null}
{
  "deliveries": [
    { "url": "https://meusite.com.br/webhooks/finvia", "status": 200, "success": true }
  ]
}
```

```json 403 theme={null}
{
  "statusCode": 403,
  "message": "Redisparo de webhook disponível apenas para cobranças de teste",
  "error": "Forbidden"
}
```

## Veja também

> [card] [Webhooks de cobrança](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md)
>
> Eventos e payloads reais de cobrança.

> [card] [Visão geral de webhooks](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md)
>
> Como cadastrar e tratar webhooks.

> [card] [Criar uma cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md)
>
> Gere a cobrança de teste.

> [card] [Roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md)
>
> Cenários CHG-08 e CHG-09.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.