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

# Educação e mensalidades

> Escolas e cursos livres com mensalidade: assinaturas por série ou curso, Pix avulso para matrícula e material, inadimplência pelas retentativas, cancelamento e Pix mensal para quem não usa cartão.

Escolas, cursos de idiomas, escolas de música e academias de esportes cobram uma mensalidade fixa, todo mês, durante o ano letivo, e algumas cobranças pontuais: matrícula, material didático, uniforme, passeio. O desafio é cobrar a mensalidade sem que o responsável precise lembrar de pagar, acompanhar quem está em atraso e oferecer uma alternativa para famílias que não usam cartão. Esta página mostra como montar isso com a API da Finvia.

> [!TIP]
>
> Quer acelerar com um assistente de IA? Copie o prompt abaixo e cole no Claude Code, no Codex, no Gemini ou no Cursor. Veja outros prompts em [Integrar com IA](https://docs.fastpaybrasil.com/integrar-com-ia.md).

Implementar este caso com um assistente de IA

Você vai integrar a API de pagamentos da Finvia neste projeto.

Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa:

* [https://docs.fastpaybrasil.com/casos-de-uso/educacao-mensalidades.md](https://docs.fastpaybrasil.com/casos-de-uso/educacao-mensalidades.md)
* [https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md](https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md)
* [https://docs.fastpaybrasil.com/guias/assinaturas/planos.md](https://docs.fastpaybrasil.com/guias/assinaturas/planos.md)
* [https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md)
* [https://docs.fastpaybrasil.com/guias/clientes.md](https://docs.fastpaybrasil.com/guias/clientes.md)
* [https://docs.fastpaybrasil.com/guias/cobrancas/pix.md](https://docs.fastpaybrasil.com/guias/cobrancas/pix.md)
* [https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md](https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md)
* [https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md](https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md)
* [https://docs.fastpaybrasil.com/homologacao/roteiro.md](https://docs.fastpaybrasil.com/homologacao/roteiro.md)

Regras que valem para toda a integração:

* Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório.
* Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento.
* Valores em reais, não em centavos: `10` significa dez reais.
* A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`.
* O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo).
* Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor.

Tarefa: implementar neste projeto o fluxo descrito na página "Educação e mensalidades" ([https://docs.fastpaybrasil.com/casos-de-uso/educacao-mensalidades.md](https://docs.fastpaybrasil.com/casos-de-uso/educacao-mensalidades.md)). Resumo do caso: Escolas e cursos livres com mensalidade: assinaturas por série ou curso, Pix avulso para matrícula e material, inadimplência pelas retentativas, cancelamento e Pix mensal para quem não usa cartão.

Siga a seção "Passo a passo" da página na ordem em que ela aparece e use o "Checklist de implementação" do fim da página para conferir o resultado.

Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia.

## O cenário

A **Escola Viva Idiomas** é uma rede de cursos de inglês e espanhol em Campinas, com 1.100 alunos ativos. A mensalidade varia por nível:

| Curso | Mensalidade |
| - | - |
| Kids (6 a 10 anos) | R\$ 289,00 |
| Teens (11 a 16 anos) | R\$ 329,00 |
| Adultos | R\$ 359,00 |

Além da mensalidade, há a **matrícula** (R\$ 150,00, uma vez por ano) e o **material didático** (R\$ 240,00 por semestre). Hoje, 70% das famílias pagam no cartão e 30% pagam por Pix todo mês.

O que a escola precisa:

* cobrar a mensalidade no cartão automaticamente, todo mês;
* cobrar matrícula e material por Pix, de forma avulsa;
* saber quem está com a mensalidade em atraso e por quê;
* cancelar a mensalidade quando o aluno sai, respeitando o prazo de arrependimento;
* gerar o Pix mensal para as famílias que não usam cartão.

## O que a Finvia resolve

> [!NOTE]
>
> **Para o negócio:** cada curso vira um plano de assinatura com o valor da mensalidade. O responsável financeiro do aluno vira um cliente, com o cartão guardado no cofre da Finvia, e a assinatura cobra esse cartão a cada ciclo. Quando a cobrança é recusada, a Finvia tenta de novo nas rodadas seguintes e envia um webhook a cada falha, com o motivo. Matrícula, material e mensalidades de quem paga por Pix são cobranças Pix avulsas, com validade em dias, confirmadas por webhook.

## Arquitetura da solução

| Necessidade | Recurso | Rota ou guia |
| - | - | - |
| Valor de cada curso | Plano de assinatura mensal | `POST /v1/subscription-plans` · [Planos](https://docs.fastpaybrasil.com/guias/assinaturas/planos.md) |
| Responsável financeiro | Cliente com e-mail e CPF | `POST /v1/customers` · [Clientes](https://docs.fastpaybrasil.com/guias/clientes.md) |
| Cartão do responsável | Cofre de cartões | `POST /v1/cards` · [Cofre de cartões](https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md) |
| Mensalidade automática | Assinatura | `POST /v1/subscriptions` · [Assinaturas](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md) |
| Matrícula e material | Cobrança Pix avulsa | `POST /v1/charges` · [Pix](https://docs.fastpaybrasil.com/guias/cobrancas/pix.md) |
| Inadimplência | `subscription.payment_failed` e `subscription.expired` | [Webhooks de assinatura](https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md) |
| Histórico por aluno | Consulta e listagem de assinaturas | `GET /v1/subscriptions/{id}` e `GET /v1/subscriptions` |
| Saída do aluno | Cancelamento | `POST /v1/subscriptions/{id}/cancel` · [Ciclo de vida](https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md) |

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

O desenho abaixo mostra como a Escola Viva cobra a matrícula por Pix e a mensalidade por assinatura no cartão.

```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
    R(["Responsável<br/>financeiro do aluno"]):::comprador
    S["Sistema da secretaria<br/>chave secreta sk_"]:::lojista
    API["Finvia API"]:::finvia
    PIX["Sistema Pix<br/>banco do responsável"]:::externo
    MOT["Renovação automática<br/>6h, 12h e 18h"]:::finvia
    ADQ["Adquirente e bandeiras<br/>cartão de crédito"]:::externo
    EV[["subscription.*<br/>e charge.paid"]]:::evento
    W["Receptor de webhooks"]:::lojista
    FIN(["Financeiro da escola<br/>baixa ou atraso"]):::ok
    S -->|"1. um plano por curso<br/>/v1/subscription-plans"| API
    R -->|"2. faz a matrícula"| S
    S ==>|"3. Pix da matrícula<br/>POST /v1/charges"| API
    S ==>|"4. cliente, cartão<br/>e assinatura"| API
    API -->|"5. QR Code de 3 dias"| PIX
    API -->|"6. mensalidade<br/>todo mês"| MOT
    MOT -->|"7. cobra o cartão"| ADQ
    API -->|"8. publica o evento"| EV
    EV -.->|"9. entrega"| W
    W ==>|"10. confere e registra"| FIN
    classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A
    classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80
    classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
```

Todo mês, a mensalidade segue um dos dois caminhos abaixo, conforme a forma de pagamento da família.

```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
    INI(["Mensalidade do mês"]):::neutro
    Q{"Como a família<br/>paga?"}:::decisao
    REN["Assinatura cobra<br/>o cartão salvo"]:::finvia
    R{"Cobrança<br/>aprovada?"}:::decisao
    OKC["active<br/>subscription.renewed<br/>baixa a mensalidade"]:::ok
    PF["active<br/>subscription.payment_failed<br/>avisa o responsável"]:::alerta
    EXP["expired<br/>subscription.expired<br/>oferecer o Pix mensal"]:::erro
    PX["Pix avulso do mês<br/>POST /v1/charges<br/>expirationInDays 10"]:::lojista
    P{"Pagou no<br/>prazo?"}:::decisao
    OKP["paid<br/>charge.paid e GET<br/>baixa a mensalidade"]:::ok
    NV["Pix venceu<br/>a escola gera<br/>uma cobrança nova"]:::alerta
    INI --> Q
    Q -->|"cartão"| REN
    Q -->|"Pix"| PX
    REN --> R
    R ==>|"sim"| OKC
    R -->|"não"| PF
    PF -->|"nova rodada<br/>6h · 12h · 18h"| REN
    PF -->|"limite de tentativas<br/>do ciclo"| EXP
    PX --> P
    P ==>|"sim"| OKP
    P -->|"não"| NV
    NV -.-> PX
    classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15
    classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209
    classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
```

A assinatura também passa a `expired` quando o plano chega ao `endDate`, no fim do ano letivo.

## Passo a passo

**1. Crie um plano por curso**

Gere a chave de API com um usuário **Owner** ou **Manager**: os perfis Desenvolvedor e Financeiro recebem `403` `Acesso negado` nas rotas de planos e assinaturas.

```bash theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/subscription-plans" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "2v2TGGb4NHTQWCiMmnelz2WVOZP",
    "name": "Inglês Teens 2026",
    "price": 329,
    "currency": "BRL",
    "recurrenceType": "monthly",
    "endDate": "2026-12-31",
    "buyerMessage": "Bem-vindo à Escola Viva Idiomas!",
    "paymentMethods": ["credit_card"],
    "status": "active"
  }'
```

A resposta `201` traz só o `id` do plano; para ver o plano completo, use `GET /v1/subscription-plans/{id}`. O `endDate` encerra as assinaturas do plano no fim do ano letivo: quando o período seguinte começaria depois dessa data, a assinatura passa a `expired` e chega `subscription.expired`. Para o ano seguinte, a escola cria um plano novo, com o valor reajustado.

> [!NOTE]
>
> Alterar o preço de um plano existente não muda as assinaturas já criadas. Preço, moeda e periodicidade ficam congelados na assinatura no momento da contratação. Por isso, a escola trabalha com um plano por curso e por ano.

**2. Cobre a matrícula por Pix**

Na matrícula, o responsável paga R\$ 150,00 por Pix. A cobrança vale 3 dias.

```bash theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150,
    "currency": "BRL",
    "customer": {
      "name": "Maria Souza",
      "email": "maria@email.com",
      "document": { "type": "cpf", "id": "52998224725" },
      "phone": "+5511987654321"
    },
    "paymentMethod": { "type": "pix", "expirationInDays": 3 },
    "items": [
      { "title": "Matrícula 2026", "type": "digital", "description": "Matrícula do aluno Pedro Souza, Inglês Teens", "unit_price": 150, "quantity": 1 }
    ],
    "metadata": { "aluno": "EV-4410", "tipo": "matricula", "ano": "2026" },
    "postbackUrl": "https://secretaria.escolaviva.exemplo.com.br/webhooks/finvia"
  }'
```

O sistema da secretaria mostra o QR Code (`qrCodeBase64`) ou envia o `copyPaste` por e-mail ou WhatsApp, e confirma a matrícula quando recebe `charge.paid` e consulta a cobrança com `GET /v1/charges/{id}`.

> [!NOTE]
>
> Os itens usam `"type": "digital"` porque matrícula e mensalidade não têm entrega. Se a escola também vender material impresso com entrega, envie o material como item `physical`: com ele, `shippingAddress` passa a ser obrigatório, e sem o endereço a API responde `400`.

**3. Cadastre o responsável e o cartão**

O pagador é o responsável financeiro do aluno. Para registrar o cartão, ele precisa de e-mail e CPF (ou CNPJ).

```bash theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/customers" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Souza",
    "email": "maria@email.com",
    "documentId": "52998224725",
    "documentType": "cpf",
    "phoneNumber": "+5511987654321"
  }'
```

```bash theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/cards" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "number": "1111222233334444",
    "holderName": "MARIA SOUZA",
    "expirationMonth": "10",
    "expirationYear": "2028",
    "cvv": "123",
    "alias": "Cartão da mensalidade"
  }'
```

O cartão nasce `active`, sem cobrança de validação. Se o responsável tiver dois filhos matriculados, o mesmo cliente e o mesmo cartão servem para as duas assinaturas. Nos exemplos, `2RhQg9M7ZCg3X3nMb9W1kX8Q` é o cliente, `2RhQgK4vN8pT1wZ6yB3mC7dF` é o cartão, `2RhQg9M7ZCg3X3nMb9W2kY9R` é o plano e `2RhQg9M7ZCg3X3nMb9W3kZ0S` é a assinatura.

**4. Crie a assinatura da mensalidade**

```bash theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/subscriptions" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R",
    "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "cardTokenId": "2RhQgK4vN8pT1wZ6yB3mC7dF",
    "metadata": { "aluno": "EV-4410", "turma": "TEENS-3B" }
  }'
```

Como o plano não tem trial, a primeira mensalidade é cobrada na criação da assinatura. Com `status` `active` na resposta, a mensalidade do primeiro mês está paga. Com `firstCharge.pending: true`, o pagamento está em análise: não crie outra assinatura e aguarde `subscription.activated` ou `subscription.payment_failed`.

Com `pending_activation` e `firstCharge.success: false`, o cartão foi recusado. A assinatura fica parada: não cobra, não renova e não tem retentativa automática. Para tentar de novo, peça outro cartão ao responsável e crie uma **nova** assinatura (ela terá outro `id`), ou ofereça o Pix mensal (variação abaixo). Cancele a assinatura pendente com `POST /v1/subscriptions/{id}/cancel` para ela não ficar na listagem.

O ciclo fica ancorado na data da contratação. No plano mensal, o dia de referência é mantido: uma matrícula em 31/01 renova em 28/02 (ou 29/02) e volta para 31/03. A renovação é feita por uma rotina que roda às 6h, 12h e 18h (horário de Brasília), depois do fim do período.

**5. Acompanhe a inadimplência**

Quando a cobrança de renovação é recusada, a Finvia tenta de novo nas rodadas seguintes (6h, 12h e 18h), até o limite de tentativas do ciclo descrito em [Ciclo de vida](https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md). Cada falha gera `subscription.payment_failed`, e a assinatura continua `active` durante as retentativas.

```javascript theme={null}
// Trecho do switch (event) do seu receptor de webhooks
switch (event) {
case 'subscription.payment_failed':
  await financeiro.registrarAtraso(data.metadata.aluno, {
    motivo: data.failure_reason,          // texto, ex.: "Cartão vencido"
    ciclo: data.charge.billing_cycle,
  });
  await comunicacao.avisarResponsavel(data.customer.email, data.failure_reason);
  break;

case 'subscription.expired':
  // Retentativas esgotadas ou fim do ano letivo (endDate do plano)
  await financeiro.marcarAssinaturaEncerrada(data.metadata.aluno);
  break;
}
```

| Situação | Status da assinatura | Evento | Ação da escola |
| - | - | - | - |
| Mensalidade paga | `active` | `subscription.renewed` | Baixar a mensalidade do mês |
| Tentativa recusada | `active` | `subscription.payment_failed` | Avisar o responsável e pedir atualização do cartão |
| Limite de tentativas do ciclo atingido | `expired` | `subscription.expired` | Tratar como inadimplente e oferecer o Pix mensal |
| Fim do plano (`endDate`) | `expired` | `subscription.expired` | Rematrícula no plano do ano seguinte |

Para saber se o `expired` veio de inadimplência ou do fim do ano letivo, compare a data com o `endDate` do plano e veja se houve `subscription.payment_failed` no ciclo.

Para a lista de alunos em cada situação, use a listagem de assinaturas com o filtro de status:

```bash theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/subscriptions?status=expired&page=1&size=50" \
  -u "$FINVIA_API_KEY:"
```

O filtro aceita `pending_activation`, `active`, `cancelled` e `expired`, e há também `customerId` e `search` (nome ou e-mail do cliente, ou nome do plano).

**6. Troque o cartão de quem está em atraso**

A assinatura não permite trocar o cartão. Quando o responsável manda um cartão novo, a escola registra o cartão, cancela a assinatura atual e cria uma nova com o `cardTokenId` novo. A nova assinatura começa um ciclo novo, com cobrança imediata da mensalidade.

> [!WARNING]
>
> Se a assinatura que está sendo trocada tiver **até 7 dias**, o cancelamento entra como arrependimento e estorna todas as cobranças pagas dela. Em trocas logo depois da matrícula, confira a data de criação antes de cancelar.

**7. Cancele quando o aluno sair**

```bash theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W3kZ0S/cancel" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Transferência do aluno para outra cidade" }'
```

O resultado segue uma regra da plataforma, aplicada a todo cancelamento e contada em dias completos desde a criação da assinatura:

| Quando | Resultado |
| - | - |
| Até 7 dias da criação da assinatura | `cancellationType: "regret"`, estorno automático de todas as cobranças pagas e acesso revogado imediatamente. Não há como cancelar nesse prazo sem estornar |
| Depois de 7 dias | `cancellationType: "regular"`, sem estorno; as cobranças param imediatamente e `accessRevokedAt` indica até quando o período pago vale |

No cancelamento regular, a escola decide até quando o aluno frequenta as aulas, com base em `accessRevokedAt`. Qualquer multa ou aviso prévio previsto no contrato escolar é uma cobrança à parte, feita pela escola.

## Regras e cuidados

> [!WARNING]
>
> **Não cobre a mensalidade com cartão salvo em `POST /v1/charges`.** Essa rota exige o CVV do responsável a cada cobrança, então não serve para cobrança automática. A mensalidade recorrente é feita pela assinatura.

* **Moeda.** Planos cobrados no cartão aceitam só `BRL`.
* **Documento do responsável.** CPF (11 dígitos) ou CNPJ (14 dígitos), com e-mail. Passaporte ou RG contam como "sem documento", e o registro do cartão é recusado com `400`.
* **Plano congelado.** Reajuste anual exige plano novo e assinatura nova.
* **Recorrência mensal.** `monthly` segue o ciclo a partir da contratação. O intervalo `custom` conta dias corridos e desliza no calendário.
* **`failure_reason` é texto.** Use para exibir e registrar. Decida o fluxo pelo evento e pelo status.
* **Recusa não gera `charge.*`.** A falha de uma mensalidade é avisada só por `subscription.payment_failed`. Cada mensalidade paga gera também `charge.created` e `charge.paid`, com `subscription_id` e `billing_cycle` no `metadata`.
* **Permissão da chave.** Chaves geradas por usuários Desenvolvedor ou Financeiro recebem `403` em todas as rotas de planos e assinaturas; Visualizador só acessa as consultas.
* **Assinaturas sem split.** As cobranças recorrentes das assinaturas não recebem split. Se a rede tiver unidades como subcontas e quiser ficar com parte da mensalidade, isso não sai automaticamente; o split só vale para cobranças avulsas em `POST /v1/charges`.

## Variações do caso

> [accordion] Pix mensal para quem não usa cartão
>
> As assinaturas cobram só no cartão. Para as famílias que pagam por Pix, o sistema da escola gera, todo mês, uma cobrança Pix avulsa alguns dias antes do vencimento:
>
> ```json theme={null}
> {
>   "amount": 329,
>   "currency": "BRL",
>   "customer": { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q" },
>   "paymentMethod": { "type": "pix", "expirationInDays": 10 },
>   "items": [
>     { "title": "Mensalidade abril 2026", "type": "digital", "description": "Inglês Teens, aluno Pedro Souza", "unit_price": 329, "quantity": 1 }
>   ],
>   "metadata": { "aluno": "EV-4410", "tipo": "mensalidade", "competencia": "2026-04" },
>   "postbackUrl": "https://secretaria.escolaviva.exemplo.com.br/webhooks/finvia"
> }
> ```
>
> A escola envia o copia e cola ao responsável e baixa a mensalidade quando recebe `charge.paid` e confirma na API. Nesse modelo, a régua de cobrança (lembretes, segunda via, atraso) é toda da escola: quando o Pix vence sem pagamento, o sistema gera uma cobrança nova. Guarde o `id` de cada cobrança junto da competência, porque a listagem de cobranças não busca por `metadata`.

> [accordion] E o material didático do semestre?
>
> O material é uma cobrança avulsa, igual à matrícula. Para parcelar no cartão, use `credit_card` com `installments` (até `12`), com o responsável presente para informar o CVV, ou com o cartão salvo (`cardTokenId` mais CVV).

> [accordion] E se a escola tiver várias unidades com CNPJ próprio?
>
> Cada unidade pode ser uma subconta no Connect da rede. As assinaturas e cobranças de cada unidade são criadas com a chave da subconta dela, e o dinheiro entra no saldo da unidade. Lembre que o cartão pertence ao merchant da chave que o registrou: um cartão registrado na unidade Centro não pode ser usado na unidade Cambuí. As mensalidades por assinatura não recebem split; a rede só consegue separar uma parte automaticamente nas cobranças avulsas, como matrícula e material. Os eventos das assinaturas de cada unidade vão para os endpoints da subconta e para um endpoint da conta master com a opção de incluir subcontas. O modelo de subcontas está em [ERP e software de gestão](https://docs.fastpaybrasil.com/casos-de-uso/erp-software-de-gestao.md).

> [accordion] E se a escola der desconto para irmãos?
>
> Crie planos com o valor já com desconto (por exemplo, "Inglês Teens 2026, segundo irmão") e use o plano certo na assinatura de cada aluno. A assinatura não aceita alteração de valor depois de criada.

## Checklist de implementação

* [ ] Um plano por curso e por ano, em `BRL`, com `endDate` no fim do ano letivo
* [ ] Responsável financeiro cadastrado com e-mail e CPF
* [ ] Cartão registrado e com `status` `active`
* [ ] Assinatura criada com `metadata` do aluno e da turma
* [ ] Tratamento de `active`, `pending_activation` e `firstCharge.pending`, com nova assinatura para tentar de novo após recusa
* [ ] Webhooks `subscription.*` com idempotência persistente
* [ ] Régua de comunicação a cada `subscription.payment_failed`
* [ ] Tratamento de `subscription.expired`, separando inadimplência de fim do ano letivo
* [ ] Troca de cartão por cancelamento e nova assinatura, considerando a janela de 7 dias
* [ ] Cobranças Pix avulsas para matrícula, material e mensalidade de quem não usa cartão
* [ ] Baixa das cobranças Pix só com `status` `paid` confirmado na API
* [ ] Homologação com cartão real de valor baixo e cancelamento no mesmo dia

## Como homologar

| Funcionalidade | Cenários |
| - | - |
| Assinaturas e cartão salvo | SUB-01 a SUB-06 |
| Pix avulso | CHG-04, CHG-05 (no Modo Teste, o Pix vira `paid` sozinho cerca de 5 segundos depois), CHG-06, CHG-08 e CHG-09 |
| Estorno de cobrança avulsa | CHG-07 |

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

## Veja também

> [card] [Assinaturas](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md)
>
> Planos, assinaturas e o fluxo cards-first.

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

> [card] [SaaS por assinatura](https://docs.fastpaybrasil.com/casos-de-uso/saas-assinaturas.md)
>
> O mesmo modelo com trial e troca de plano.

> [card] [Cobrança por mensagem](https://docs.fastpaybrasil.com/casos-de-uso/cobranca-por-link.md)
>
> Como enviar o Pix por WhatsApp ou e-mail.


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