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

# Criar um plano

> Cadastra um plano de assinatura com preço, moeda, periodicidade e, se quiser, período de trial.

O plano é o "produto" que o seu cliente assina: ele define **quanto** cobrar, **em que moeda** e **de quanto em quanto tempo**. Toda assinatura nasce a partir de um plano, então esta é a primeira rota que você chama ao montar uma oferta recorrente, como uma mensalidade de software, um clube de assinatura ou uma escola com cobrança mensal.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Mensalidade de software (SaaS) | `recurrenceType` `monthly` |
| Clube com entrega semanal ou quinzenal | `recurrenceType` `weekly` ou `biweekly` |
| Plano trimestral, semestral ou outro intervalo | `recurrenceType` `custom` com `recurrenceInterval` |
| Oferta com degustação grátis ou paga | Objeto `trial` |
| Campanha com data para acabar | `endDate` |
| Mudar o preço de um plano existente | Use [Atualizar plano](https://docs.fastpaybrasil.com/referencia/planos/atualizar.md). As assinaturas existentes mantêm o preço da contratação |

## Antes de chamar

* Tenha uma chave secreta gerada por usuário com a permissão **criar 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 `merchantId` da conta que vai vender o plano.
* Defina a periodicidade e, se houver, as regras do trial. O preço e a periodicidade ficam congelados em cada assinatura no momento da contratação: editar o plano depois só vale para assinaturas novas.

> [!WARNING]
>
> Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste, inclusive a validação de R\$ 1,00 do trial grátis. Veja como homologar em [Assinaturas: visão geral](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md).

> [!WARNING]
>
> O valor vai em **reais**: `"price": 99.9` significa R\$ 99,90. Planos cobrados no cartão aceitam apenas a moeda `BRL`.

## Corpo da requisição

Campos obrigatórios: `merchantId`, `name`, `price`, `currency` e `recurrenceType`.

**merchantId** `string` *required*

ID do merchant que vai vender o plano. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`.

**name** `string` *required*

Nome do plano. Ex.: `Plano Premium Mensal`.

**price** `number` *required*

Preço cobrado a cada ciclo, na unidade da moeda (ex.: `99.90` = R\$ 99,90).

**currency** `string` *required*

Código da moeda no padrão ISO 4217. Ex.: `BRL`. Planos cobrados no cartão aceitam apenas `BRL`.

**recurrenceType** `string` *required*

Periodicidade da cobrança:

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

**recurrenceInterval** `integer`

Intervalo da recorrência personalizada, **em dias corridos**. Inteiro maior que zero, obrigatório quando `recurrenceType` é `custom`. Ex.: `90` (cobrança a cada 90 dias). Nos tipos `weekly`, `biweekly` e `monthly`, o campo é ignorado.

> [!WARNING]
>
> `custom` com `30` não é igual a `monthly`. O mensal mantém o dia do mês da contratação; o `custom` só soma dias, e a data da cobrança desliza conforme o calendário. Para cobrar todo mês no mesmo dia, use `monthly`.

**endDate** `string`

Data de término do plano, no padrão ISO 8601 (formato `date`). Ex.: `2025-12-31`. Quando o período seguinte de uma assinatura começaria depois dessa data, a assinatura é encerrada com status `expired`.

**buyerMessage** `string`

Mensagem exibida ao comprador. Ex.: `Bem-vindo ao Plano Premium!`.

**paymentMethods** `string[]`

Formas de pagamento aceitas. Ex.: `["credit_card"]`.

**trial** `object`

Período de trial (teste) opcional. Quando informado, os novos assinantes passam pelo trial antes do primeiro ciclo cobrado com o valor cheio.

**propriedades**

**durationDays** `integer` *required*

Duração do trial em dias. Mínimo `1`, máximo `365`. Ex.: `14`.

**isFree** `boolean` *required*

`true` para trial grátis. `false` para trial pago, que exige `price`.

**price** `number`

Valor cobrado durante o trial, em reais. Obrigatório quando `isFree` é `false`. Ex.: `9.9`.

**status** `string` (default: active)

Status inicial do plano: `active` (aceita novas assinaturas) ou `inactive` (não aceita).

### Como o trial afeta a primeira cobrança

| Configuração | O que acontece ao criar a assinatura |
| - | - |
| Sem `trial` | A primeira cobrança com o valor cheio é feita na criação da assinatura e valida o cartão |
| Trial grátis (`isFree: true`) | Nada da mensalidade é cobrado no início. Para validar o cartão, a Finvia cobra R\$ 1,00 e estorna em seguida |
| Trial pago (`isFree: false`) | O valor do trial é cobrado na criação da assinatura e valida o cartão |
| Assinatura criada com `skipTrial: true` | O trial é ignorado e o valor cheio é cobrado na criação da assinatura |

Ao fim do trial, a primeira cobrança cheia é processada no ciclo normal de cobrança.

> [!NOTE]
>
> **Para o negócio:** no trial grátis, o comprador pode ver na fatura do cartão duas linhas de R\$ 1,00 (a cobrança de validação e o estorno, que é feito logo depois, de forma assíncrona). Avise o comprador disso no checkout. Se a validação for recusada, ficar em análise ou o processador não responder, a assinatura não é criada e a API responde `422 CARD_VALIDATION_FAILED`.

## Respostas

A resposta `201` traz só o `id` do plano. Para ver o plano completo, chame [Consultar plano](https://docs.fastpaybrasil.com/referencia/planos/consultar.md).

**id** `string`

Identificador único do plano. Guarde este valor: ele vai em `subscriptionPlanId` ao [criar a assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/criar.md).

| HTTP | Significado | Corpo |
| - | - | - |
| `201` | Plano criado | `{"id": "..."}` |
| `400` | Método desconhecido em `paymentMethods` | `message` começando com `Invalid payment methods:` |
| `400` | Erro de validação do corpo | `message` em lista |
| `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` |
| `403` | O usuário que gerou a chave não tem a permissão criar assinaturas | `{"message": "Acesso negado", "error": "Forbidden", "statusCode": 403}` |
| `404` | `merchantId` de uma conta a que a chave não tem acesso | `Merchant not found` |
| `404` | Moeda inexistente em `currency` | `Currency not found` |

## Exemplos por caso de uso

> [tab] Mensal (SaaS)
>
> Plano mensal de um software de gestão, sem trial.
>
> ```json theme={null}
> {
>   "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
>   "name": "Plano Profissional Mensal",
>   "price": 149.9,
>   "currency": "BRL",
>   "recurrenceType": "monthly",
>   "buyerMessage": "Obrigado por assinar o Plano Profissional!",
>   "paymentMethods": ["credit_card"]
> }
> ```

> [tab] Trial grátis de 14 dias
>
> O assinante usa 14 dias sem pagar a mensalidade. O cartão é validado com R\$ 1,00, estornado em seguida.
>
> ```json theme={null}
> {
>   "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
>   "name": "Plano Premium Mensal",
>   "price": 99.9,
>   "currency": "BRL",
>   "recurrenceType": "monthly",
>   "paymentMethods": ["credit_card"],
>   "trial": { "durationDays": 14, "isFree": true }
> }
> ```

> [tab] Trial pago
>
> Primeiro mês promocional a R\$ 9,90, depois R\$ 99,90 por mês.
>
> ```json theme={null}
> {
>   "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
>   "name": "Plano Premium Mensal",
>   "price": 99.9,
>   "currency": "BRL",
>   "recurrenceType": "monthly",
>   "paymentMethods": ["credit_card"],
>   "trial": { "durationDays": 30, "isFree": false, "price": 9.9 }
> }
> ```

> [tab] Personalizado com data de término
>
> Plano cobrado a cada 90 dias que deixa de renovar depois do fim do ano.
>
> ```json theme={null}
> {
>   "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
>   "name": "Mensalidade Curso Técnico",
>   "price": 350,
>   "currency": "BRL",
>   "recurrenceType": "custom",
>   "recurrenceInterval": 90,
>   "endDate": "2025-12-31",
>   "paymentMethods": ["credit_card"],
>   "status": "active"
> }
> ```

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `403` com `Acesso negado` | O usuário que gerou a chave não tem a permissão criar assinaturas (ex.: perfil 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) |
| `404` com `Merchant not found` | `merchantId` de outra conta, ou com erro de digitação | Use o id da conta dona da chave ou de uma subconta a que ela tem acesso |
| `404` com `Currency not found` | Código de moeda inexistente | Envie um código ISO 4217 válido, como `BRL` |
| `400` com `Invalid payment methods` | Método desconhecido em `paymentMethods` | Envie só métodos válidos, como `credit_card` |
| `401` | Chave ausente, inválida ou header montado errado | Monte o header com o Base64 de `sua_chave:` |
| Plano com moeda diferente de `BRL` não serve para cartão | Planos cobrados no cartão aceitam só `BRL` | Use `currency` `BRL` |
| Trial pago sem valor | `isFree: false` sem `trial.price` | Envie `trial.price` |
| Data de cobrança "deslizando" no plano `custom` | O intervalo conta dias corridos | Use `monthly` se quiser cobrar todo mês |

```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": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "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": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "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: '2RhQg9M7ZCg3X3nMb9W1kX8Q',
    name: 'Plano Premium Mensal',
    price: 99.9,
    currency: 'BRL',
    recurrenceType: 'monthly',
    buyerMessage: 'Bem-vindo ao Plano Premium!',
    paymentMethods: ['credit_card'],
    trial: { durationDays: 14, isFree: true },
  }),
});

const { id } = await response.json();
// Para ver o plano completo: GET /v1/subscription-plans/{id}
```

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

import requests

payload = {
    "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "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' => '2RhQg9M7ZCg3X3nMb9W1kX8Q',
    '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": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
              "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": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "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": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
	  "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" => "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "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
```

```json 201 theme={null}
{
  "id": "2RhQg9M7ZCg3X3nMb9W2kY9R"
}
```

```json 403 theme={null}
{
  "message": "Acesso negado",
  "error": "Forbidden",
  "statusCode": 403
}
```

## 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] [Criar assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/criar.md)
>
> Vincule um cliente ao plano e faça a primeira cobrança.


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