> ## 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.

# Estornar uma cobrança

> Solicita o estorno total de uma cobrança paga, em Pix ou cartão de crédito.

Esta rota devolve ao cliente o valor **inteiro** de uma cobrança paga. Ela atende cancelamento de pedido, desistência de compra, produto indisponível depois da venda e qualquer outro caso em que o dinheiro precisa voltar ao comprador. Funciona para cobranças pagas com Pix e com cartão de crédito (inclusive cartão salvo e Apple Pay).

> [!WARNING]
>
> Esta rota é o **único caminho para pedir um estorno**. A Finvia não faz estorno por chamado ou pelo suporte, exceto em caso de erro sistêmico. Integre esta chamada ao seu sistema ou ao seu processo de atendimento.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Cliente cancelou o pedido | Envie o `chargeId` e o motivo do cancelamento |
| Produto sem estoque depois da venda | Estorne e registre o motivo para auditoria |
| Cobrança duplicada por erro da sua integração | Estorne a cobrança repetida |
| Devolver só parte do valor | Não é possível. A API faz apenas estorno total |
| Assinatura cancelada em até 7 dias | O cancelamento da assinatura já estorna as cobranças pagas. Veja [Cancelar assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/cancelar.md) |

## Antes de chamar

* Tenha uma chave secreta do mesmo ambiente da cobrança ([Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)).
* A cobrança precisa estar com `status` `paid`. Confira com [`GET /v1/charges/{id}`](https://docs.fastpaybrasil.com/referencia/cobrancas/consultar). Uma cobrança bloqueada (`isBlocked: true`) continua `paid` e pode ser estornada.
* O pedido precisa partir da conta dona da cobrança. Em venda com split, o recebedor não consegue estornar.
* Cada cobrança aceita **um único estorno**.

## Corpo da requisição

Os dois campos são obrigatórios.

**chargeId** `string` *required*

ID da cobrança a ser estornada. A cobrança precisa estar com status `paid`. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`.

**reason** `string` *required*

Motivo do estorno, em texto livre. Fica registrado para auditoria. Ex.: `Pedido ORD-123 cancelado pelo cliente`.

## Respostas

**status** `string`

Resultado do estorno. Hoje a API devolve sempre `refunded`: o estorno foi registrado na Finvia e o valor saiu do seu saldo.

**reason** `string | null`

Texto informado pelo provedor de pagamento (PSP). Pode vir preenchido mesmo quando o estorno deu certo: decida pelo `status`, não por este campo.

**pspRefundRefId** `string | null`

Identificador do estorno no PSP, quando disponível. Ex.: `ref_abc123`.

Com o `201`, a cobrança passa a `refunded` e o webhook `charge.refunded` é enviado aos endpoints do painel e à `postbackUrl` da cobrança. Se a adquirente ou o banco não concluir o estorno automaticamente, a API responde `refunded` mesmo assim e a equipe Finvia conclui o estorno manualmente. Nesse caso o comprador pode demorar mais para receber. Não reenvie o pedido: se o comprador não receber, acione o suporte com o `chargeId`.

| HTTP | Significado | `message` |
| - | - | - |
| `201` | Estorno registrado | Corpo com `status`, `reason`, `pspRefundRefId` |
| `400` | Corpo inválido (campo ausente ou de tipo errado) | Lista de mensagens de validação |
| `401` | Credencial inválida | `Unauthorized` |
| `403` | Perfil do usuário dono da chave sem permissão | `Acesso negado` |
| `404` | Cobrança inexistente ou que não está `paid` (pendente, já estornada, `pre_chargeback`, `chargeback` e outros) | `Cobrança não encontrada` |
| `422` | Já existe um estorno para esta cobrança | `Já existe um reembolso para esta cobrança` |
| `501` | Método de pagamento ou provedor sem estorno | `Reembolso não implementado para este método de pagamento` ou `Reembolso não disponível para este provedor de pagamento` |
| `500` | Erro interno | |

Os erros seguem o formato padrão, com `statusCode`, `message` e `error`. Trate pelo código HTTP, não pelo texto.

> [!NOTE]
>
> **Para o negócio:** o comprador recebe o valor integral da cobrança. Do seu saldo sai o valor bruto da venda, e as taxas da venda não são devolvidas. Prazos para o comprador receber, efeito no split e estorno depois do saque estão no [guia de estorno](https://docs.fastpaybrasil.com/guias/estorno.md).

## Evite estorno duplicado

A API não aceita o cabeçalho `Idempotency-Key`, mas recusa um segundo estorno da mesma cobrança. A proteção fica assim:

**1. Grave o resultado**

Ao receber o `201`, grave o `status` e o `pspRefundRefId` junto com a cobrança. A resposta não traz um campo `id` do estorno.

**2. Trate o 422 como final**

`422` `Já existe um reembolso para esta cobrança` indica que o estorno já foi feito. Não repita o pedido.

**3. Depois de um timeout, consulte a cobrança**

Chame `GET /v1/charges/{id}`. Se ela estiver `refunded`, grave o resultado e não envie outro pedido.

O [guia de estorno](https://docs.fastpaybrasil.com/guias/estorno.md) traz uma rotina completa em Node.js.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `404` `Cobrança não encontrada` para uma cobrança que existe | A cobrança não está `paid` (pendente, já estornada, em `pre_chargeback` ou `chargeback`) ou é de outro ambiente | Consulte a cobrança. Só cobranças `paid` podem ser estornadas |
| `422` no segundo pedido | A cobrança já tem um estorno | Não reenvie. Acompanhe pelo `charge.refunded` ou pela consulta |
| `501` | Método ou provedor sem estorno pela API | Só Pix e cartão têm estorno |
| `403` | A chave herda as permissões do usuário que a gerou | Confira o perfil do usuário que gerou a chave ([Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)) |
| Esperava devolver parte do valor | A rota faz só estorno total | Não há estorno parcial na API |
| Recebedor do split não consegue estornar | O estorno é pedido pela conta dona da cobrança | Peça o estorno com a chave do originador |

## Como testar

No sandbox, com a chave `sk_test_`:

* **CHG-07:** estorno total de uma cobrança paga. Resultado esperado: status `refunded` e webhook `charge.refunded`.
* **AP-05:** estorno de uma cobrança Apple Pay paga, se você usa Apple Pay.

Detalhes e evidências em [Roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md).

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

{
  "chargeId": "2vorkDcXyvzifL63YX09S9VqcnI",
  "reason": "Pedido ORD-123 cancelado pelo cliente"
}
```

```bash cURL theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/refunds" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "chargeId": "2vorkDcXyvzifL63YX09S9VqcnI",
    "reason": "Pedido ORD-123 cancelado pelo cliente"
  }'
```

```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/refunds', {
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    chargeId: '2vorkDcXyvzifL63YX09S9VqcnI',
    reason: 'Pedido ORD-123 cancelado pelo cliente',
  }),
});

if (response.status === 201) {
  const refund = await response.json();
  console.log('Estorno registrado:', refund.status, refund.pspRefundRefId);
} else if (response.status === 422) {
  console.log('A cobrança já tinha um estorno. Nada a fazer.');
} else {
  const erro = await response.json();
  console.warn('Estorno não aceito:', response.status, erro.message);
}
```

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

import requests

payload = {
    "chargeId": "2vorkDcXyvzifL63YX09S9VqcnI",
    "reason": "Pedido ORD-123 cancelado pelo cliente",
}

response = requests.request(
    "POST",
    "https://api-global.fastpaybrasil.com/v1/refunds",
    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 = [
    'chargeId' => '2vorkDcXyvzifL63YX09S9VqcnI',
    'reason' => 'Pedido ORD-123 cancelado pelo cliente',
];

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/refunds');

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 = """
            {
              "chargeId": "2vorkDcXyvzifL63YX09S9VqcnI",
              "reason": "Pedido ORD-123 cancelado pelo cliente"
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/refunds"))
            .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 = """
{
  "chargeId": "2vorkDcXyvzifL63YX09S9VqcnI",
  "reason": "Pedido ORD-123 cancelado pelo cliente"
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/refunds");
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(`{
	  "chargeId": "2vorkDcXyvzifL63YX09S9VqcnI",
	  "reason": "Pedido ORD-123 cancelado pelo cliente"
	}`)

	req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/refunds", 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/refunds")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "chargeId" => "2vorkDcXyvzifL63YX09S9VqcnI",
  "reason" => "Pedido ORD-123 cancelado pelo cliente",
})

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}
{
  "status": "refunded",
  "reason": null,
  "pspRefundRefId": "ref_abc123"
}
```

```json 404 theme={null}
{
  "statusCode": 404,
  "message": "Cobrança não encontrada",
  "error": "Not Found"
}
```

```json 422 theme={null}
{
  "statusCode": 422,
  "message": "Já existe um reembolso para esta cobrança",
  "error": "Unprocessable Entity"
}
```

## Veja também

> [card] [Guia de estorno](https://docs.fastpaybrasil.com/guias/estorno.md)
>
> Prazos, saldo, split e estorno depois do saque.

> [card] [Consultar cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/consultar.md)
>
> Confira o status antes e depois do estorno.

> [card] [Webhooks de cobrança](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md)
>
> Payload do evento `charge.refunded`.

> [card] [Bloqueio, chargeback e MED](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md)
>
> Quando o estorno vem de uma contestação.


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