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

# Alterar status do plano

> Ativa ou desativa um plano para novas assinaturas. A desativação pede uma confirmação em segunda etapa.

Esta rota abre ou fecha um plano para novas vendas. Desativar um plano impede novas assinaturas nele, sem mexer nas assinaturas que já existem: elas continuam sendo cobradas normalmente. Por segurança, a desativação **sempre** acontece em duas etapas, com ou sem assinaturas ativas no plano: esta rota devolve um token de confirmação e o plano só fica inativo depois de [Confirmar desativação](https://docs.fastpaybrasil.com/referencia/planos/confirmar-desativacao.md). A ativação é imediata.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Encerrar a venda de um plano antigo | `status` `inactive` e, em seguida, confirmar com o token |
| Pausar uma oferta temporária | `status` `inactive` e confirmar. Reative depois com `active` |
| Voltar a vender um plano desativado | `status` `active`. A ativação é imediata, sem confirmação |
| Cancelar as assinaturas de quem já está no plano | Esta rota não faz isso. Use [Cancelar assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/cancelar.md) em cada assinatura |

## Antes de chamar

* Tenha uma chave secreta gerada por usuário com a permissão **atualizar 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)).
* Tenha o `id` do plano.
* Para desativar, prepare a aplicação para chamar a confirmação logo em seguida: o token vale por 5 minutos e só pode ser usado uma vez.

> [!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).

## Como funciona a desativação

**1. Solicite a desativação**

Chame esta rota com `{"status": "inactive"}`. A resposta traz sempre `requiresConfirmation: true` e um `confirmationToken`. Pedir a desativação de novo gera outro token e invalida o anterior.

**2. Confirme em até 5 minutos**

Envie o `confirmationToken` para `PATCH /v1/subscription-plans/{id}/status/confirm`. A resposta `204` indica que o plano foi desativado. O token é de uso único.

**3. Confira o resultado**

Consulte o plano: `status` passa a ser `inactive`. As assinaturas existentes seguem ativas e renovando normalmente. Para encerrá-las, cancele uma a uma.

## Parâmetros de caminho

**id** `string` *required*

Identificador único do plano. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`.

## Corpo da requisição

**status** `string` *required*

Novo status do plano: `active` ou `inactive`. Ex.: `inactive`.

## Respostas

A resposta `200` nunca traz o objeto do plano. O formato depende do status pedido.

| Pedido | Resposta `200` | Efeito |
| - | - | - |
| `{"status": "inactive"}` | `{ "requiresConfirmation": true, "confirmationToken": "..." }` | Nada muda até a confirmação |
| `{"status": "active"}` | `{ "requiresConfirmation": false }` | O plano é ativado na hora |

**requiresConfirmation** `boolean`

`true` ao pedir a desativação (sempre). `false` ao ativar.

**confirmationToken** `string`

Só ao desativar. Token para [Confirmar desativação](https://docs.fastpaybrasil.com/referencia/planos/confirmar-desativacao.md). Ex.: `abc123xyz`. Vale por 5 minutos e é de uso único. Um novo pedido de desativação gera outro token e invalida o anterior.

| HTTP | Significado | Corpo |
| - | - | - |
| `200` | Desativação pedida (aguarda confirmação) ou plano ativado | `requiresConfirmation` e, ao desativar, `confirmationToken` |
| `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` |
| `403` | O usuário que gerou a chave não tem a permissão atualizar assinaturas | `{"message": "Acesso negado", "error": "Forbidden", "statusCode": 403}` |
| `404` | Plano não encontrado | `{"statusCode": 404, "message": "Subscription plan not found"}` |

> [!NOTE]
>
> **Para o negócio:** desativar um plano tira o produto da prateleira, mas **não** encerra a receita recorrente de quem já assinou. Se a intenção é descontinuar o serviço por completo, além de desativar o plano é preciso cancelar cada assinatura, considerando as regras de cancelamento (estorno automático em até 7 dias da criação da assinatura).

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| Plano continua `active` depois de pedir `inactive` | Faltou a segunda etapa | Chame [Confirmar desativação](https://docs.fastpaybrasil.com/referencia/planos/confirmar-desativacao.md) com o `confirmationToken` |
| `400` "Invalid or expired confirmation token" na confirmação | Token usado depois de 5 minutos, já usado, errado ou substituído por um pedido mais recente | Peça a desativação de novo e confirme com o token mais recente |
| `404` com "Subscription plan not found" | `id` errado ou de outra conta | Confira o `id` na [listagem de planos](https://docs.fastpaybrasil.com/referencia/planos/listar.md) |
| `403` com `Acesso negado` | O usuário que gerou a chave não tem a permissão atualizar 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) |
| Assinantes antigos continuam sendo cobrados | Comportamento documentado: desativar o plano não afeta assinaturas existentes | Cancele as assinaturas que precisam ser encerradas |

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

{
  "status": "inactive"
}
```

```bash cURL theme={null}
curl -X PATCH "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{"status": "inactive"}'
```

```javascript Node.js theme={null}
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
const base = 'https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q';
const headers = { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json' };

// 1. Solicita a desativação
const res = await fetch(`${base}/status`, {
  method: 'PATCH',
  headers,
  body: JSON.stringify({ status: 'inactive' }),
});
const body = await res.json();

// 2. Confirma em seguida (o token vale por 5 minutos)
if (body.requiresConfirmation) {
  const confirm = await fetch(`${base}/status/confirm`, {
    method: 'PATCH',
    headers,
    body: JSON.stringify({ confirmationToken: body.confirmationToken }),
  });
  // confirm.status === 204 indica plano desativado
}
```

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

import requests

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

response = requests.request(
    "PATCH",
    "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status",
    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' => 'inactive',
];

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

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    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": "inactive"
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status"))
            .header("Authorization", "Basic " + credentials)
            .header("Content-Type", "application/json")
            .method("PATCH", 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": "inactive"
}
""";

var request = new HttpRequestMessage(HttpMethod.Patch, "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status");
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": "inactive"
	}`)

	req, err := http.NewRequest("PATCH", "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status", 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/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/status")
request = Net::HTTP::Patch.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "status" => "inactive",
})

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 Desativação theme={null}
{
  "requiresConfirmation": true,
  "confirmationToken": "abc123xyz"
}
```

```json 200 Ativação theme={null}
{
  "requiresConfirmation": false
}
```

```json 404 theme={null}
{
  "statusCode": 404,
  "message": "Subscription plan not found"
}
```

## Veja também

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

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

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

> [card] [Webhooks de assinatura](https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md)
>
> Eventos enviados a cada etapa da assinatura.

> [card] [Registrar cartão](https://docs.fastpaybrasil.com/referencia/cartoes/registrar.md)
>
> Guarde o cartão no cofre antes de criar a assinatura.

> [card] [Confirmar desativação](https://docs.fastpaybrasil.com/referencia/planos/confirmar-desativacao.md)
>
> Segunda etapa da desativação do plano.


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