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

# Planos de assinatura

> Defina preço, periodicidade e período de teste dos planos que os seus clientes vão assinar.

O plano é o "produto" da assinatura: diz quanto custa, em que moeda e de quanto em quanto tempo o cliente é cobrado. Cada assinatura nasce de um plano. Um mesmo plano atende quantos assinantes você tiver.

> [!NOTE]
>
> **Para o negócio:** o time comercial ou de produto define os planos (ex.: Básico mensal R\$ 49,90, Premium mensal R\$ 99,90, Anual com desconto) e o time técnico os cadastra uma vez. Alterar o preço de um plano vale só para quem assinar depois: os assinantes atuais continuam com o preço contratado. Para mudar o preço de quem já assina, é preciso cancelar a assinatura e criar outra.

## Quando usar

| Situação | O que fazer |
| - | - |
| Lançar um novo plano | Criar o plano com `POST /v1/subscription-plans` |
| Oferecer período de teste | Configurar `trial` no plano (grátis ou pago) |
| Mudar o preço para novos clientes | Atualizar com `PUT /v1/subscription-plans/{id}` |
| Parar de vender um plano sem afetar quem já assina | Desativar com `PATCH /v1/subscription-plans/{id}/status` e confirmar |
| Campanha com prazo de término | Usar `endDate` no plano |
| Mostrar o plano na página de vendas | Enviar uma imagem com `POST /v1/subscription-plans/{id}/image` |

## Como funciona

**1. Crie o plano**

Defina nome, preço, moeda `BRL`, recorrência e, se quiser, trial e mensagem ao comprador.

**2. Opcional: envie a imagem**

A imagem aparece em `imageUrl` nas consultas do plano.

**3. Use o plano nas assinaturas**

Envie o `id` do plano em `subscriptionPlanId` ao criar cada assinatura.

**4. Ajuste ou desative quando precisar**

Atualizações e desativação afetam só as novas assinaturas.

## Regras de negócio

| Regra | Detalhe |
| - | - |
| Campos obrigatórios | `merchantId`, `name`, `price`, `currency`, `recurrenceType` |
| Moeda | Planos cobrados no cartão aceitam apenas `BRL` |
| Valor | Em reais: `99.9` significa R\$ 99,90 |
| Status inicial | `active` por padrão |
| Atualização | **Não** afeta assinaturas existentes. Preço e periodicidade ficam congelados na assinatura no momento da contratação; editar o plano só vale para assinaturas novas |
| Desativação | **Não** afeta assinaturas existentes. Só impede novas assinaturas no plano |
| Confirmação | Desativar sempre exige confirmação com um token válido por 5 minutos e de uso único |
| Permissão | Criar exige a permissão criar assinaturas; consultar e listar, visualizar assinaturas; atualizar, enviar imagem e mudar o status, atualizar assinaturas. Veja [Permissões por perfil](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md#permissões-por-perfil) |
| Trial | De 1 a 365 dias, grátis ou pago |

> [!WARNING]
>
> Mudar o preço de um plano **não** reajusta os assinantes atuais. Se a sua estratégia é reajustar a base, o caminho é cancelar a assinatura de cada cliente e criar uma nova no plano atualizado, com nova cobrança imediata. Planeje a comunicação com o cliente antes.

## Tipos de recorrência

| `recurrenceType` | Cobrança |
| - | - |
| `weekly` | Semanal |
| `biweekly` | Quinzenal |
| `monthly` | Mensal |
| `custom` | Intervalo personalizado, em dias, definido em `recurrenceInterval` |

Para recorrência personalizada, informe `recurrenceInterval` **em dias**:

```json theme={null}
{
  "recurrenceType": "custom",
  "recurrenceInterval": 90
}
```

Esse plano cobra a cada 90 dias.

> [!WARNING]
>
> O intervalo `custom` conta **dias corridos**. `custom` com `30` não é igual a `monthly`: o mensal mantém o dia do mês da contratação, e o `custom` só soma dias, então a data da cobrança desliza conforme o calendário. Da mesma forma, "a cada 60 dias" não é "bimestral no mesmo dia do mês". Se o cliente espera ser cobrado sempre no mesmo dia do mês, use `monthly`. Nos tipos `weekly`, `biweekly` e `monthly`, `recurrenceInterval` é ignorado.

## Trial (período de teste)

O plano pode ter um período de teste, grátis ou pago, configurado no objeto `trial`:

```json theme={null}
{
  "trial": {
    "durationDays": 14,
    "isFree": true
  }
}
```

| Campo | Tipo | Descrição |
| - | - | - |
| `durationDays` | integer | Duração do trial em dias (mínimo `1`, máximo `365`). Obrigatório no objeto |
| `isFree` | boolean | `true` = trial grátis; `false` = trial pago (exige `price`). Obrigatório no objeto |
| `price` | number | Valor cobrado no trial. Obrigatório quando `isFree` é `false` |

### Como cada caso se comporta na criação da assinatura

| Caso | Cobrança na criação | Validação do cartão |
| - | - | - |
| **Trial grátis** (`isFree: true`) | Nenhum valor de mensalidade | A Finvia cobra **R\$ 1,00** e estorna em seguida |
| **Trial pago** (`isFree: false`) | O valor do trial (`trial.price`), imediatamente | A própria cobrança valida o cartão |
| **Sem trial** | A primeira cobrança cheia, imediatamente | A própria cobrança valida o cartão |
| **`skipTrial: true`** na assinatura | O valor cheio, imediatamente, ignorando o trial do plano | A própria cobrança valida o cartão |

O desenho abaixo mostra o caminho de cada caso, da criação da assinatura até a primeira cobrança cheia.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"defaultRenderer": "elk", "curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
flowchart TB
    IN(["POST /v1/subscriptions"]):::neutro
    Q1{"skipTrial: true?"}:::decisao
    Q2{"O plano<br/>tem trial?"}:::decisao
    Q3{"Trial grátis<br/>isFree: true?"}:::decisao
    CHE["Cobra o valor cheio<br/>na criação"]:::finvia
    VAL["Cobra R$ 1,00 e estorna<br/>para validar o cartão<br/>sem webhook"]:::finvia
    PAG["Cobra trial.price<br/>na criação"]:::finvia
    E422["422 CARD_VALIDATION_FAILED<br/>nada é criado"]:::erro
    A1[["subscription.activated"]]:::evento
    A2[["subscription.activated<br/>com o objeto trial"]]:::evento
    TRI["Período de trial<br/>durationDays: 1 a 365"]:::alerta
    FIM["Fim do trial<br/>primeira cobrança cheia"]:::finvia
    R2[["subscription.renewed<br/>com o objeto trial"]]:::evento
    C1(["Ciclo ancorado<br/>na contratação"]):::ok
    C2(["Ciclo ancorado<br/>no fim do trial"]):::ok
    PEN(["pending_activation<br/>veja Ciclo de vida"]):::erro
    IN --> Q1
    Q1 -->|"sim"| CHE
    Q1 -->|"não"| Q2
    Q2 -->|"não"| CHE
    Q2 -->|"sim"| Q3
    Q3 -->|"sim"| VAL
    Q3 -->|"não, trial pago"| PAG
    VAL -->|"recusada, em análise<br/>ou sem resposta"| E422
    VAL -->|"aprovada"| A2
    PAG -->|"aprovada"| A2
    CHE -->|"aprovada"| A1
    A1 --> C1
    A2 --> TRI
    TRI --> FIM
    FIM -->|"aprovada"| R2
    R2 --> C2
    PAG -->|"recusada ou<br/>em análise"| PEN
    CHE -->|"recusada ou<br/>em análise"| PEN
    classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600
    classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
    classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209
    classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

Ao fim do trial, a primeira cobrança cheia é processada no ciclo normal. Em planos com trial, a ativação e a primeira cobrança cheia geram os webhooks `subscription.activated` e `subscription.renewed`, com o objeto `trial` no payload.

### Validação de R\$ 1,00 no trial grátis

> [!WARNING]
>
> No trial grátis, o comprador pode ver **duas linhas na fatura**: a cobrança de R\$ 1,00 e o estorno. **Avise-o no checkout** (por exemplo: "Para validar o seu cartão, faremos uma cobrança de R\$ 1,00 que será estornada em seguida").

* A validação só acontece em plano com trial grátis, quando a assinatura é criada sem `skipTrial: true`. O estorno do R\$ 1,00 é assíncrono.
* Se a validação for **recusada, ficar em análise ou o processador não responder**, a resposta é `422` com `{ "code": "CARD_VALIDATION_FAILED", "message": "Não foi possível validar o cartão: <motivo>" }`, e nada é criado: nem assinatura, nem webhook. Se ficou em análise, oriente o comprador a usar outro cartão.
* `409 CARD_VALIDATION_IN_PROGRESS`: já há uma validação do mesmo cartão em andamento (requisição repetida em paralelo).
* `429 CARD_VALIDATION_RATE_LIMITED`: 3 recusas do mesmo cartão em 24 horas, ou 30 recusas na mesma conta em 1 hora.
* Os três erros vêm no formato `{ code, message }`. Decida o fluxo pelo `code` e use a `message` só para exibir.
* Se a mesma requisição (mesmo merchant, cliente, cartão e plano) for reenviada em até **15 minutos**, a API reaproveita a validação aprovada e não cobra o R\$ 1,00 de novo. A resposta `201` traz `cardValidation: { "validated": true, "amount": 1 }`.
* A cobrança de validação e o estorno dela **não geram webhooks**.

> [!TIP]
>
> **Para o desenvolvedor:** se a criação falhar por outro motivo depois da validação (por exemplo, um erro de rede na sua aplicação), repita a mesma requisição dentro de 15 minutos. Assim o cliente não é cobrado de novo pela validação.

## Status do plano

| Status | Significado |
| - | - |
| `active` | Plano disponível para novas assinaturas |
| `inactive` | Plano indisponível para novas assinaturas |

Desativar um plano não afeta as assinaturas existentes, que continuam sendo cobradas normalmente.

O desenho abaixo mostra como o plano muda de status, com a confirmação que a desativação sempre exige.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
flowchart TB
    NOVO(["Plano criado<br/>/v1/subscription-plans"]):::neutro
    ACT["active<br/>aceita novas assinaturas"]:::ok
    TOK["requiresConfirmation: true<br/>confirmationToken<br/>vale 5 min, uso único"]:::alerta
    INA["inactive<br/>não aceita novas assinaturas"]:::neutro
    E400["400 Invalid or expired<br/>confirmation token<br/>o plano segue active"]:::erro
    EXI(["Assinaturas existentes<br/>continuam renovando"]):::ok
    E404["Nova assinatura no plano<br/>404 Subscription plan<br/>not found or inactive"]:::erro
    NOVO -->|"padrão"| ACT
    NOVO -.->|"criado com<br/>status: inactive"| INA
    ACT -->|"1. PATCH .../status<br/>status: inactive"| TOK
    TOK -->|"2. PATCH .../status/confirm<br/>em até 5 min · 204"| INA
    TOK -.->|"token errado,<br/>vencido ou já usado"| E400
    INA -->|"PATCH .../status<br/>status: active, na hora"| ACT
    INA -.-> EXI
    INA -.-> E404
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
    classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209
    classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

## Passo a passo

### 1. Criar o plano

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

{
  "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
  "name": "Plano Premium Mensal",
  "price": 99.9,
  "currency": "BRL",
  "recurrenceType": "monthly",
  "buyerMessage": "Bem-vindo ao Plano Premium!",
  "paymentMethods": [
    "credit_card"
  ],
  "status": "active"
}
```

```bash cURL theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/subscription-plans" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
    "name": "Plano Premium Mensal",
    "price": 99.90,
    "currency": "BRL",
    "recurrenceType": "monthly",
    "buyerMessage": "Bem-vindo ao Plano Premium!",
    "paymentMethods": ["credit_card"],
    "status": "active"
  }'
```

```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/subscription-plans', {
  method: 'POST',
  headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    merchantId: '36OO3bcGjhPjjF3tzrqOGcmQuKo',
    name: 'Plano Premium Mensal',
    price: 99.9,
    currency: 'BRL',
    recurrenceType: 'monthly',
    buyerMessage: 'Bem-vindo ao Plano Premium!',
    paymentMethods: ['credit_card'],
  }),
});

const { id } = await response.json(); // a resposta 201 traz só o id
```

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

import requests

payload = {
    "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
    "name": "Plano Premium Mensal",
    "price": 99.9,
    "currency": "BRL",
    "recurrenceType": "monthly",
    "buyerMessage": "Bem-vindo ao Plano Premium!",
    "paymentMethods": [
        "credit_card",
    ],
    "status": "active",
}

response = requests.request(
    "POST",
    "https://api-global.fastpaybrasil.com/v1/subscription-plans",
    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 = [
    'merchantId' => '36OO3bcGjhPjjF3tzrqOGcmQuKo',
    'name' => 'Plano Premium Mensal',
    'price' => 99.9,
    'currency' => 'BRL',
    'recurrenceType' => 'monthly',
    'buyerMessage' => 'Bem-vindo ao Plano Premium!',
    'paymentMethods' => [
        'credit_card',
    ],
    'status' => 'active',
];

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

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 = """
            {
              "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
              "name": "Plano Premium Mensal",
              "price": 99.9,
              "currency": "BRL",
              "recurrenceType": "monthly",
              "buyerMessage": "Bem-vindo ao Plano Premium!",
              "paymentMethods": [
                "credit_card"
              ],
              "status": "active"
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/subscription-plans"))
            .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 = """
{
  "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
  "name": "Plano Premium Mensal",
  "price": 99.9,
  "currency": "BRL",
  "recurrenceType": "monthly",
  "buyerMessage": "Bem-vindo ao Plano Premium!",
  "paymentMethods": [
    "credit_card"
  ],
  "status": "active"
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/subscription-plans");
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(`{
	  "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
	  "name": "Plano Premium Mensal",
	  "price": 99.9,
	  "currency": "BRL",
	  "recurrenceType": "monthly",
	  "buyerMessage": "Bem-vindo ao Plano Premium!",
	  "paymentMethods": [
	    "credit_card"
	  ],
	  "status": "active"
	}`)

	req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/subscription-plans", 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")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "merchantId" => "36OO3bcGjhPjjF3tzrqOGcmQuKo",
  "name" => "Plano Premium Mensal",
  "price" => 99.9,
  "currency" => "BRL",
  "recurrenceType" => "monthly",
  "buyerMessage" => "Bem-vindo ao Plano Premium!",
  "paymentMethods" => [
    "credit_card",
  ],
  "status" => "active",
})

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

puts response.code
puts response.body
```

| Campo | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `merchantId` | string | Sim | ID do merchant dono do plano |
| `name` | string | Sim | Nome do plano |
| `price` | number | Sim | Preço em reais (ex.: `99.90` = R\$ 99,90) |
| `currency` | string | Sim | Código ISO 4217. Para cartão, `BRL` |
| `recurrenceType` | string | Sim | `weekly`, `biweekly`, `monthly` ou `custom` |
| `recurrenceInterval` | integer | Com `custom` | Intervalo da recorrência personalizada, em dias corridos (inteiro maior que zero). Ex.: `90` |
| `endDate` | string (date) | Não | Data de término do plano (ISO 8601, ex.: `2025-12-31`) |
| `buyerMessage` | string | Não | Mensagem exibida ao comprador |
| `paymentMethods` | string\[] | Não | Formas de pagamento aceitas (ex.: `["credit_card"]`) |
| `trial` | object | Não | Configuração do período de teste |
| `status` | string | Não | `active` (padrão) ou `inactive` |

A resposta `201` traz só o `id` do plano. Para ver o plano completo, use a [consulta](#2-consultar-e-listar-planos).

```json theme={null}
{
  "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q"
}
```

Erros específicos da criação: `404 Merchant not found` (o `merchantId` não é de uma conta a que a chave tem acesso), `404 Currency not found` (moeda inexistente) e `400 Invalid payment methods: ...` (método desconhecido em `paymentMethods`).

#### Exemplos de planos

> [tab] Mensal com trial grátis
>
> ```json theme={null}
> {
>   "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
>   "name": "Plano Básico Mensal",
>   "price": 49.9,
>   "currency": "BRL",
>   "recurrenceType": "monthly",
>   "paymentMethods": ["credit_card"],
>   "trial": { "durationDays": 7, "isFree": true }
> }
> ```

> [tab] Semanal com trial pago
>
> ```json theme={null}
> {
>   "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
>   "name": "Marmitas Fit Semanal",
>   "price": 189.9,
>   "currency": "BRL",
>   "recurrenceType": "weekly",
>   "paymentMethods": ["credit_card"],
>   "trial": { "durationDays": 7, "isFree": false, "price": 9.9 }
> }
> ```

> [tab] Trimestral com data de término
>
> ```json theme={null}
> {
>   "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
>   "name": "Curso Intensivo Trimestral",
>   "price": 299,
>   "currency": "BRL",
>   "recurrenceType": "custom",
>   "recurrenceInterval": 90,
>   "endDate": "2025-12-31",
>   "paymentMethods": ["credit_card"]
> }
> ```
>
> Quando o próximo período começaria depois de `endDate`, a assinatura é encerrada com status `expired`.

### 2. Consultar e listar planos

```bash cURL theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q" \
  -u "$FINVIA_API_KEY:"
```

```json theme={null}
{
  "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
  "name": "Plano Premium Mensal",
  "price": 99.9,
  "currency": "BRL",
  "recurrenceType": "monthly",
  "recurrenceInterval": null,
  "endDate": null,
  "buyerMessage": "Bem-vindo ao Plano Premium!",
  "paymentMethods": ["credit_card"],
  "imageUrl": "https://storage.example.com/plans/image.png",
  "status": "active",
  "activeSubscriptionsCount": 150,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}
```

`activeSubscriptionsCount` mostra quantas assinaturas ativas o plano tem, útil para o time de negócio acompanhar a base de cada plano.

A listagem `GET /v1/subscription-plans` é paginada e aceita `merchantId`, `status` (`active` ou `inactive`), `page` (padrão `1`) e `size` (padrão `10`). A resposta traz `data` e `meta` (`total`, `page`, `limit`, `totalPages`).

```bash cURL theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/subscription-plans?status=active&page=1&size=10" \
  -u "$FINVIA_API_KEY:"
```

Existe ainda a listagem de cobranças do plano, `GET /v1/subscription-plans/{id}/charges`. Cada item traz `id` (o registro de cobrança da assinatura), `chargeId` (o id da cobrança, usado em `GET /v1/charges/{id}`), `subscriptionId` e `billingCycle`. É o caminho para relacionar o histórico de [Consultar assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/consultar.md) às cobranças. `chargeId` vem `null` quando a tentativa nem chegou ao processador.

> [!TIP]
>
> **Para o desenvolvedor:** antes de levar o cliente ao checkout, consulte o plano e confirme que `status` é `active`. Um plano inativo faz a criação da assinatura falhar com `404` `Subscription plan not found or inactive`.

### 3. Enviar a imagem do plano

A imagem é enviada como arquivo (`multipart/form-data`, campo `file`), em PNG, JPG ou JPEG. A resposta é `204`, sem corpo.

```bash cURL theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/image" \
  -u "$FINVIA_API_KEY:" \
  -F "file=@plano-premium.png"
```

Depois do envio, a URL da imagem aparece em `imageUrl` na consulta do plano.

### 4. Atualizar o plano

`PUT /v1/subscription-plans/{id}` exige `merchantId` e aceita os demais campos que você quer mudar: `name`, `price`, `currency`, `recurrenceType`, `recurrenceInterval`, `endDate`, `buyerMessage`, `paymentMethods` e `trial`. Para remover o trial, envie `"trial": null`.

```bash cURL theme={null}
curl -X PUT "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
    "name": "Plano Premium Atualizado",
    "price": 119.9
  }'
```

A resposta `200` traz só o `id` do plano. Para conferir as alterações, consulte o plano. As mudanças valem **só para novas assinaturas**.

### 5. Desativar o plano

A desativação é feita em duas etapas. A primeira chamada **sempre** pede confirmação, tenha o plano assinaturas ativas ou não. Essa rota nunca devolve o objeto do plano.

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

```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"}'
```

Resposta:

```json theme={null}
{
  "requiresConfirmation": true,
  "confirmationToken": "abc123xyz"
}
```

O token vale 5 minutos e é de uso único. Pedir a desativação de novo gera outro token e invalida o anterior.

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

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

Resposta `204`, sem corpo. O plano fica `inactive`. Token errado, vencido ou já usado: `400 Invalid or expired confirmation token`. Plano inexistente ou de outra conta: `404 Subscription plan not found`.

> [!NOTE]
>
> **Para o negócio:** a confirmação existe para evitar desativações por engano. Se a sua equipe opera planos por um painel interno, mostre a quantidade de assinaturas ativas (`activeSubscriptionsCount`, na consulta do plano) antes de confirmar. Lembre que desativar não cancela ninguém: os assinantes atuais continuam renovando normalmente. Para encerrá-los, é preciso cancelar uma a uma.

Para **reativar**, envie `"status": "active"` para a mesma rota. A resposta é `{ "requiresConfirmation": false }` e o plano é ativado imediatamente.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `400` `Invalid or expired confirmation token` | Token errado, já usado, substituído por um pedido mais recente ou confirmação depois de 5 minutos | Solicite a desativação de novo e confirme em seguida |
| `404` `Subscription plan not found` | `id` do plano incorreto | Confira o `id` com a listagem |
| Assinantes antigos continuam pagando o preço anterior | A atualização do plano não afeta assinaturas existentes | Comportamento esperado. Para reajustar, cancele e crie nova assinatura |
| `422 CARD_VALIDATION_FAILED` na assinatura | Validação de R\$ 1,00 do trial grátis recusada, em análise ou sem resposta do processador | Peça outro cartão ao comprador |
| `404` `Merchant not found` ou `Currency not found` ao criar | `merchantId` sem acesso pela chave, ou moeda inexistente | Confira o `merchantId` e use `BRL` |
| `400` `Invalid payment methods` ao criar | Método desconhecido em `paymentMethods` | Envie só métodos válidos, como `credit_card` |
| Cobrança em data diferente da esperada no plano `custom` | O intervalo conta dias corridos | Ajuste a comunicação ou use `monthly` |
| `403` `Acesso negado` | O usuário que gerou a chave não tem a permissão da rota | Gere a chave com Owner ou Manager. Veja [Permissões por perfil](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md#permissões-por-perfil) |

## Perguntas frequentes

> [accordion] Posso ter vários planos ativos ao mesmo tempo?
>
> Sim. Cada plano é independente e cada assinatura aponta para um plano.

> [accordion] Mudei o preço do plano. O que acontece com quem já assina?
>
> Nada. Preço, moeda e periodicidade ficam congelados na assinatura no momento da contratação. Só novas assinaturas usam o preço atualizado.

> [accordion] Desativar um plano cancela as assinaturas?
>
> Não. As assinaturas existentes continuam ativas e renovando normalmente. O plano só deixa de aceitar novas assinaturas. Para encerrar as assinaturas, cancele uma a uma.

> [accordion] O cliente vai ver a cobrança de R\$ 1,00 do trial grátis?
>
> Pode ver duas linhas na fatura: a cobrança e o estorno. A documentação orienta avisar o comprador no checkout.

> [accordion] Posso dar trial só para alguns clientes?
>
> O trial é configurado no plano. Para um cliente específico pular o trial, crie a assinatura com `skipTrial: true`, o que cobra o valor cheio imediatamente. Para oferecer trial só a um grupo, crie um plano separado com trial.

## Como testar

| Código | Cenário | O que comprovar |
| - | - | - |
| SUB-03 | Criar plano em `BRL` | Retorna o `id` do plano |
| SUB-04 | Criar assinatura no plano | Status `active` e primeira cobrança processada |

A criação do plano não movimenta dinheiro. As assinaturas criadas a partir dele são reais mesmo com a chave de teste.

## Veja também

> [card] [Assinaturas: visão geral](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md)
>
> O fluxo completo da assinatura.

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

> [card] [Criar plano](https://docs.fastpaybrasil.com/referencia/planos/criar.md)
>
> Contrato completo da rota.

> [card] [Alterar status do plano](https://docs.fastpaybrasil.com/referencia/planos/alterar-status.md)
>
> Ativar e desativar planos.


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