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

# Cancelar uma assinatura

> Cancela uma assinatura. Até 7 dias da criação, estorna as cobranças pagas; depois disso, interrompe as cobranças sem estorno.

Esta rota encerra a cobrança recorrente de uma assinatura. O efeito depende de **quando** o cancelamento acontece: em até 7 dias da criação, o cancelamento é do tipo arrependimento (`regret`) e estorna automaticamente todas as cobranças pagas; depois disso, as próximas cobranças não acontecem e não há estorno. A mesma rota é o primeiro passo para trocar o cartão ou o plano, já que a assinatura não aceita essas mudanças.

> [!WARNING]
>
> A janela de 7 dias é uma **regra da plataforma** e vale para todo cancelamento feito nela, venha do lojista ou da Finvia, por qualquer motivo, também em venda entre empresas. Ela conta a partir da **criação da assinatura** (não da primeira cobrança nem da entrega), em dias completos: um cancelamento feito até 7 dias e 23 horas depois da criação ainda é `regret`. Não existe opção para cancelar dentro da janela sem estornar.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Cliente desistiu logo após assinar | Cancele em até 7 dias: as cobranças pagas são estornadas (`regret`) |
| Cliente pediu para sair depois de meses | Cancele: as cobranças param e o acesso vale até o fim do período pago (`regular`) |
| Trocar o cartão ou o plano | Cancele e crie outra assinatura em [Criar assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/criar.md) |
| Limpar uma assinatura `pending_activation` depois de criar outra com novo cartão | Cancele a pendente. Ela não cobra nada enquanto está pendente |
| Homologação | Cancele no mesmo dia da criação para estornar a cobrança real do teste |
| Estornar uma única cobrança avulsa | Use [Estornar cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/estornar.md) |

## Antes de chamar

* Tenha uma chave secreta gerada por usuário com a permissão **cancelar assinaturas**. Nos perfis padrão, são **Owner**, **Manager** e **Operador**. Os perfis Visualizador, Desenvolvedor e Financeiro recebem `403` (veja [Permissões por perfil](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md#permissões-por-perfil)).
* A assinatura não pode estar `cancelled` nem `expired`. Nesses casos a resposta é `400`.

> [!WARNING]
>
> Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste. Veja como homologar em [Assinaturas: visão geral](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md).

## Tipos de cancelamento

| | Arrependimento (`regret`) | Regular (`regular`) |
| - | - | - |
| Quando | Até 7 dias após a criação da assinatura (contados em dias completos) | Depois de 7 dias |
| Estorno | Todas as cobranças pagas da assinatura: trial pago, primeira cobrança e renovações dentro do período | Não há estorno |
| `refunded` | `true` se havia cobrança paga e todas foram estornadas; `false` se não havia cobrança paga (ex.: trial grátis) ou se um estorno não foi concluído | `false` |
| Status | `cancelled` | `cancelled`, e as cobranças param imediatamente |
| Acesso | Encerrado na hora (`accessRevokedAt`) | Continua até `accessRevokedAt`, o fim do período já pago (`current_period_end`). Quem controla esse acesso é a sua plataforma |
| Webhook | `subscription.cancelled` com `cancellation_type: "regret"` | `subscription.cancelled` com `cancellation_type: "regular"` e `refunded: false` |

> [!NOTE]
>
> **Para o negócio:** no cancelamento regular, a Finvia apenas para de cobrar: liberar ou bloquear o acesso ao serviço até `accessRevokedAt` é responsabilidade da sua plataforma. Defina essa regra com o time de produto antes de colocar o cancelamento no ar.

## Parâmetros de caminho

**id** `string` *required*

Identificador único da assinatura. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`.

## Corpo da requisição

O corpo é opcional.

**reason** `string`

Motivo do cancelamento. Máximo de 500 caracteres (`maxLength` 500). Ex.: `Cliente solicitou cancelamento`.

## Respostas

A resposta `200` tem um de dois formatos, conforme o tipo de cancelamento.

### Arrependimento (até 7 dias)

**id** `string`

ID da assinatura.

**status** `string`

Status da assinatura: `cancelled`.

**cancellationType** `string`

Tipo de cancelamento: `regret`.

**refunded** `boolean`

`true` quando havia cobranças pagas e todas foram estornadas. `false` quando não havia o que estornar (ex.: trial grátis) ou quando um estorno não foi concluído.

**refundId** `string | null`

ID do estorno. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`.

**accessRevokedAt** `string`

Momento em que o acesso foi revogado (formato `date-time`).

### Regular (depois de 7 dias)

**id** `string`

ID da assinatura.

**status** `string`

Status da assinatura: `cancelled`.

**cancellationType** `string`

Tipo de cancelamento: `regular`.

**refunded** `boolean`

`false` no cancelamento regular. (O contrato usa a mesma descrição do campo nas outras rotas: `true` só quando havia cobranças pagas e todas foram estornadas no arrependimento.)

**accessRevokedAt** `string | null`

Data até a qual o acesso do comprador continua valendo (fim do período pago), no formato `date-time`. O status já é `cancelled` e as cobranças já pararam: a sua plataforma mantém o acesso até essa data.

| HTTP | Significado | Corpo |
| - | - | - |
| `200` | Assinatura cancelada | Formato de arrependimento ou regular |
| `400` | Assinatura já cancelada ou expirada | `{"statusCode": 400, "message": "Subscription already cancelled or expired"}` |
| `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` |
| `403` | O usuário que gerou a chave não tem a permissão cancelar assinaturas | `{"message": "Acesso negado", "error": "Forbidden", "statusCode": 403}` |
| `404` | Assinatura não encontrada | `{"statusCode": 404, "message": "Subscription not found"}` |

> [!NOTE]
>
> Depois do cancelamento, a Finvia envia o webhook `subscription.cancelled`, com `cancelled_at`, `cancellation_type` e `refunded`. Veja [Webhooks de assinatura](https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md).

> [!TIP]
>
> **Para o desenvolvedor:** decida o acesso pelo `cancellationType`. Com `regret`, revogue imediatamente. Com `regular`, guarde o `accessRevokedAt` e mantenha o acesso até essa data. Não use `refunded` para decidir o acesso: ele pode vir `false` também no arrependimento (trial grátis ou estorno não concluído).

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `400` "Subscription already cancelled or expired" | Assinatura já encerrada | Consulte o status em [Consultar assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/consultar.md) antes de cancelar |
| `404` "Subscription not found" | `id` errado ou de outra conta | Confira o `id` em [Listar assinaturas](https://docs.fastpaybrasil.com/referencia/assinaturas/listar.md) |
| `403` com `Acesso negado` | O usuário que gerou a chave não tem a permissão cancelar assinaturas (ex.: Visualizador, Desenvolvedor ou Financeiro) | Gere a chave com um usuário Owner ou Manager. Veja [Permissões por perfil](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md#permissões-por-perfil) |
| `refunded: false` em cancelamento dentro de 7 dias | Não havia cobrança paga (trial grátis) ou um estorno não foi concluído | Confira o histórico de `charges` na consulta da assinatura |
| Cliente perdeu o acesso antes do fim do período pago | Acesso revogado pelo status `cancelled` no cancelamento regular | Mantenha o acesso até `accessRevokedAt` |
| Cobrança de homologação não estornada | Cancelamento feito depois da janela de 7 dias | Cancele no mesmo dia da criação durante a homologação |

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

{
  "reason": "Cliente solicitou cancelamento"
}
```

```bash cURL theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q/cancel" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Cliente solicitou cancelamento"
  }'
```

```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/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q/cancel',
  {
    method: 'POST',
    headers: {
      Authorization: `Basic ${credentials}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ reason: 'Cliente solicitou cancelamento' }),
  },
);

const result = await response.json();
if (result.cancellationType === 'regret') {
  // revogue o acesso agora
} else {
  // mantenha o acesso até result.accessRevokedAt
}
```

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

import requests

payload = {
    "reason": "Cliente solicitou cancelamento",
}

response = requests.request(
    "POST",
    "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q/cancel",
    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 = [
    'reason' => 'Cliente solicitou cancelamento',
];

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q/cancel');

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 = """
            {
              "reason": "Cliente solicitou cancelamento"
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q/cancel"))
            .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 = """
{
  "reason": "Cliente solicitou cancelamento"
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q/cancel");
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(`{
	  "reason": "Cliente solicitou cancelamento"
	}`)

	req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q/cancel", 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/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q/cancel")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "reason" => "Cliente solicitou cancelamento",
})

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

puts response.code
puts response.body
```

```json 200 Arrependimento theme={null}
{
  "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "status": "cancelled",
  "cancellationType": "regret",
  "refunded": true,
  "refundId": "2RhQg9M7ZCg3X3nMb9W4kA1T",
  "accessRevokedAt": "2024-01-16T10:30:00.000Z"
}
```

```json 200 Regular theme={null}
{
  "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "status": "cancelled",
  "cancellationType": "regular",
  "refunded": false,
  "accessRevokedAt": "2024-02-15T10:30:00.000Z"
}
```

```json 400 theme={null}
{
  "statusCode": 400,
  "message": "Subscription already cancelled or expired"
}
```

## Veja também

> [card] [Ciclo de vida](https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md)
>
> Status, renovação, retentativas e cancelamento.

> [card] [Visão geral de assinaturas](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md)
>
> Fluxo completo, do cliente à cobrança recorrente.

> [card] [Planos](https://docs.fastpaybrasil.com/guias/assinaturas/planos.md)
>
> Recorrência, trial e status do plano.

> [card] [Webhooks de assinatura](https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md)
>
> Payload do `subscription.cancelled`.

> [card] [Registrar cartão](https://docs.fastpaybrasil.com/referencia/cartoes/registrar.md)
>
> Registre o novo cartão antes de recriar a assinatura.

> [card] [Homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md)
>
> Cenário SUB-06: cancelar dentro de 7 dias.


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