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

# SaaS por assinatura

> Software cobrado todo mês no cartão: planos, trial, cartão salvo, renovação automática, retentativas, troca de plano, cancelamento e controle de acesso por webhook.

Uma empresa de software por assinatura precisa cobrar o cliente automaticamente a cada ciclo, sem pedir o cartão de novo, e manter o acesso ao sistema alinhado com a situação do pagamento: liberar quando entra, avisar quando falha, bloquear quando a assinatura acaba. Esta página mostra como montar esse ciclo com as assinaturas 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/saas-assinaturas.md](https://docs.fastpaybrasil.com/casos-de-uso/saas-assinaturas.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/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 "SaaS por assinatura" ([https://docs.fastpaybrasil.com/casos-de-uso/saas-assinaturas.md](https://docs.fastpaybrasil.com/casos-de-uso/saas-assinaturas.md)). Resumo do caso: Software cobrado todo mês no cartão: planos, trial, cartão salvo, renovação automática, retentativas, troca de plano, cancelamento e controle de acesso por webhook.

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 **Agenda Clara** é um software de agendamento para salões de beleza e barbearias, com sede em Recife. Ela tem 2.400 clientes pagantes e três planos:

| Plano | Preço | O que inclui |
| - | - | - |
| Essencial | R\$ 59,90 por mês | 1 profissional |
| Equipe | R\$ 129,90 por mês | Até 5 profissionais |
| Rede | R\$ 299,90 por mês | Profissionais ilimitados e várias unidades |

Todo cliente novo ganha **14 dias grátis** para testar. A Agenda Clara quer cobrar no cartão de crédito, renovar sozinha todo mês e bloquear o acesso de quem deixar de pagar, sem planilha e sem cobrança manual.

## O que a Finvia resolve

> [!NOTE]
>
> **Para o negócio:** a assinatura liga um cliente, um plano e um cartão guardado no cofre da Finvia. A partir daí, a Finvia cobra sozinha a cada ciclo, tenta de novo quando a cobrança é recusada e envia um webhook a cada mudança: ativação, renovação, falha, cancelamento e expiração. O sistema da Agenda Clara usa esses avisos para liberar ou bloquear o acesso. Pela regra da plataforma, o cancelamento em até 7 dias da criação da assinatura estorna automaticamente as cobranças pagas dela.

## Arquitetura da solução

| Necessidade | Recurso | Rota ou guia |
| - | - | - |
| Definir preço e periodicidade | Plano de assinatura | `POST /v1/subscription-plans` · [Planos](https://docs.fastpaybrasil.com/guias/assinaturas/planos.md) |
| Período de teste | Objeto `trial` no plano | `POST /v1/subscription-plans` |
| Cadastro do pagador | Cliente com e-mail e CPF ou CNPJ | `POST /v1/customers` · [Clientes](https://docs.fastpaybrasil.com/guias/clientes.md) |
| Guardar o cartão | Cofre de cartões (fluxo cards-first) | `POST /v1/cards` · [Cofre de cartões](https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md) |
| Cobrança automática | Assinatura | `POST /v1/subscriptions` · [Assinaturas](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md) |
| Liberar e bloquear acesso | Webhooks `subscription.*` | [Webhooks de assinatura](https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md) |
| Histórico de cobranças | Consulta da assinatura | `GET /v1/subscriptions/{id}` |
| Cancelamento | Cancelar assinatura | `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, 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).

O desenho abaixo mostra quem faz o quê na assinatura da Agenda Clara, da criação dos planos ao controle de acesso.

```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
    C(["Salão ou barbearia<br/>contrata um plano"]):::comprador
    S["Servidor da Agenda Clara<br/>chave secreta sk_"]:::lojista
    API["Finvia API"]:::finvia
    COF["Cofre de cartões<br/>cartão nasce active"]:::finvia
    MOT["Renovação automática<br/>rodadas às 6h, 12h e 18h"]:::finvia
    ADQ["Adquirente e bandeiras<br/>cartão de crédito"]:::externo
    EV[["Eventos subscription.*<br/>activated · renewed<br/>payment_failed · expired"]]:::evento
    W["Receptor de webhooks<br/>endpoint cadastrado"]:::lojista
    AC["Controle de acesso<br/>da Agenda Clara"]:::lojista
    OK(["Acesso liberado até<br/>current_period_end"]):::ok
    S -->|"1. cria os planos<br/>/v1/subscription-plans"| API
    C -->|"2. escolhe o plano<br/>e informa o cartão"| S
    S -->|"3. POST /v1/customers<br/>e POST /v1/cards"| API
    S ==>|"4. POST /v1/subscriptions<br/>plano · cliente · cartão"| API
    API -->|"5. guarda o cartão"| COF
    API -->|"6. agenda os ciclos"| MOT
    MOT -->|"7. cobra no fim do trial<br/>e a cada mês"| ADQ
    API -->|"8. publica o evento"| EV
    EV -.->|"9. entrega"| W
    W -->|"10. libera, avisa<br/>ou bloqueia"| AC
    AC ==> OK
    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
```

Este segundo desenho acompanha a vida de uma assinatura no plano com 14 dias grátis: validação do cartão, renovações, retentativas e cancelamento.

```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(["POST /v1/subscriptions<br/>plano com 14 dias grátis"]):::neutro
    V{"Validação de<br/>R$ 1,00 no cartão?"}:::decisao
    E422["422<br/>CARD_VALIDATION_FAILED<br/>nada é criado"]:::erro
    ACT["active<br/>subscription.activated<br/>libera o acesso"]:::ok
    REN{"Cobrança<br/>do ciclo?"}:::decisao
    RNW["active<br/>subscription.renewed<br/>estende o acesso"]:::ok
    PF["active<br/>subscription.payment_failed<br/>avisa e mantém o acesso"]:::alerta
    EXP["expired<br/>subscription.expired<br/>bloqueia o acesso"]:::erro
    CAN{"Cancelou até 7 dias<br/>da criação?"}:::decisao
    REG["cancelled · regret<br/>estorna as pagas<br/>e bloqueia na hora"]:::erro
    REGU["cancelled · regular<br/>sem estorno, acesso<br/>até current_period_end"]:::neutro
    INI --> V
    V -->|"recusada ou<br/>em análise"| E422
    V ==>|"aprovada e<br/>estornada em seguida"| ACT
    ACT ==>|"fim do trial e,<br/>depois, de cada mês"| REN
    REN ==>|"aprovada"| RNW
    RNW -.->|"próximo ciclo"| REN
    REN -->|"recusada"| PF
    PF -->|"nova rodada<br/>6h · 12h · 18h"| REN
    PF -->|"limite de tentativas<br/>do ciclo"| EXP
    ACT -->|"cliente pede<br/>o cancelamento"| CAN
    CAN -->|"sim"| REG
    CAN -->|"não"| REGU
    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 neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
```

Em plano sem trial, a primeira mensalidade é cobrada na criação, e uma recusa deixa a assinatura em `pending_activation`, como mostra o passo "Trate a resposta da criação".

## Passo a passo

**1. Confira o perfil de quem gera a chave**

A chave de API age com o perfil do usuário que a gerou. Para integrar assinaturas, gere a chave com um usuário **Owner** ou **Manager**. Os perfis Desenvolvedor e Financeiro recebem `403` `Acesso negado` em todas as rotas de planos e assinaturas, e o perfil Visualizador só acessa as consultas.

**2. Crie os planos**

Cada plano define nome, preço em reais, moeda e recorrência. Planos cobrados no cartão aceitam só `BRL`. O `merchantId` é o ID da sua conta na Finvia.

```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": "Agenda Clara Equipe Mensal",
    "price": 129.9,
    "currency": "BRL",
    "recurrenceType": "monthly",
    "buyerMessage": "Bem-vindo ao plano Equipe da Agenda Clara!",
    "paymentMethods": ["credit_card"],
    "trial": { "durationDays": 14, "isFree": true },
    "status": "active"
  }'
```

A resposta `201` traz só o `id` do plano. Para ver o plano completo, use `GET /v1/subscription-plans/{id}`. Repita para Essencial e Rede.

> [!NOTE]
>
> Editar um plano depois (`PUT /v1/subscription-plans/{id}`) **não muda** as assinaturas existentes: preço e periodicidade ficam congelados na assinatura no momento da contratação. A edição vale só para assinaturas novas.

**3. Cadastre o cliente**

Para registrar cartão, o cliente precisa de **e-mail** e de **CPF ou CNPJ**. A API identifica o tipo pela quantidade de dígitos do documento: 11 é CPF e 14 é CNPJ. Passaporte ou RG contam como "sem documento", e o registro do cartão é recusado com `400` `Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador`. Como a Agenda Clara atende empresas, ela usa o CNPJ do salão quando houver.

```bash theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/customers" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Salão Bela Ana",
    "email": "ana@email.com",
    "documentId": "11222333000181",
    "documentType": "cnpj",
    "phoneNumber": "+5511987654321"
  }'
```

**4. Registre o cartão (cards-first)**

O fluxo recomendado é registrar o cartão antes de criar a assinatura. O cartão já nasce `active`, sem transação de teste e sem etapa de ativação.

```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": "ANA LIMA",
    "expirationMonth": "10",
    "expirationYear": "2028",
    "cvv": "123"
  }'
```

```json theme={null}
{
  "id": "2RhQgK4vN8pT1wZ6yB3mC7dF",
  "token": "tok_abc123xyz",
  "maskedNumber": "****4444",
  "status": "active",
  "pendingActivation": false
}
```

O cartão pertence ao merchant da chave que o registrou. Ele não pode ser usado por outra conta ou subconta. O registro é real mesmo com a chave de teste, mas não cobra nada.

**5. Crie a assinatura**

Com plano, cliente e cartão, a assinatura é criada com três IDs diferentes: o do plano, o do cliente e o do cartão.

```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": { "contaAgendaClara": "AC-55821" }
  }'
```

O que acontece depende do trial do plano:

| Plano | O que a Finvia faz na criação |
| - | - |
| Trial grátis (`isFree: true`) | Cobra R\$ 1,00 para validar o cartão e estorna em seguida. A mensalidade só é cobrada no fim do trial |
| Trial pago (`isFree: false`) | Cobra o valor do trial na criação |
| Sem trial | Cobra a primeira mensalidade cheia na criação |
| `skipTrial: true` na assinatura | Ignora o trial do plano e cobra o valor cheio na criação |

No trial grátis, se a cobrança de R\$ 1,00 for recusada, ficar em análise ou ficar sem resposta do processador, a API responde `422` com `code` `CARD_VALIDATION_FAILED` e nada é criado: nem assinatura, nem webhook. A `message` traz o motivo no formato `Não foi possível validar o cartão: <motivo>`. Decida o fluxo pelo `code` e use a `message` só para exibir. Reenviar a mesma requisição (mesmo cliente, cartão e plano) em até 15 minutos reaproveita uma validação aprovada sem cobrar R\$ 1,00 de novo. Com sucesso, a resposta `201` traz `cardValidation: { "validated": true, "amount": 1 }`.

> [!TIP]
>
> **Para o desenvolvedor:** avise no checkout que o cliente pode ver uma cobrança de R\$ 1,00 e o estorno na fatura. O estorno é feito logo depois, de forma assíncrona.

**6. Trate a resposta da criação**

| Resposta | Significado | O que fazer |
| - | - | - |
| `status` `active` | Assinatura ativa | Liberar o acesso |
| `status` `pending_activation` e `firstCharge.success: false` | Primeira cobrança recusada | Pedir outro cartão e criar uma nova assinatura |
| `status` `pending_activation` e `firstCharge.pending: true` | Pagamento em análise | **Não** criar outra assinatura. Aguardar `subscription.activated` ou `subscription.payment_failed` |
| `422` `CARD_VALIDATION_FAILED` | Validação do trial grátis recusada, em análise ou sem resposta | Pedir outro cartão |
| `409` `CARD_VALIDATION_IN_PROGRESS` | A mesma validação já está em andamento (requisição repetida em paralelo) | Aguardar a primeira requisição |
| `429` `CARD_VALIDATION_RATE_LIMITED` | 3 recusas do mesmo cartão em 24 horas, ou 30 recusas na conta em 1 hora | Pedir outro cartão e esperar antes de tentar de novo |
| `404` "Subscription plan not found or inactive" | Plano inexistente ou inativo | Conferir o plano com `GET /v1/subscription-plans/{id}` |
| `403` `Acesso negado` | O perfil de quem gerou a chave não tem permissão | Gerar a chave com Owner ou Manager |

Uma assinatura em `pending_activation` não cobra, não renova e não tem retentativa automática. Ela só passa a `active` sozinha quando a primeira cobrança estava em análise e a análise aprovou. Se a cobrança foi recusada, a API não tenta de novo: para outra tentativa (por exemplo, com outro cartão), crie uma nova assinatura com `POST /v1/subscriptions`. A nova terá outro `id`. A pendente pode ser cancelada com `POST /v1/subscriptions/{id}/cancel` para não ficar na listagem.

**7. Controle o acesso pelos webhooks**

Cadastre o endpoint no painel, em **Configurações** > **Webhooks**, ou pela API em `POST /v1/webhook-endpoints`. Assinaturas não têm `postbackUrl`: os eventos chegam só aos endpoints. Eles usam o envelope padrão (`id`, `event`, `livemode`, `data`), com campos em snake\_case; o objeto `trial` vem em camelCase e o `metadata` volta como foi enviado.

```javascript theme={null}
app.post('/webhooks/finvia', async (req, res) => {
  const { id, event, data } = req.body;
  if (await eventos.jaProcessado(id)) return res.status(200).send('OK');
  res.status(200).send('OK');

  const conta = data.metadata?.contaAgendaClara;
  switch (event) {
    case 'subscription.activated':
    case 'subscription.renewed':
      await acesso.liberarAte(conta, data.current_period_end);
      break;
    case 'subscription.payment_failed':
      // A assinatura continua active durante as retentativas
      await avisos.pedirAtualizacaoDeCartao(conta, data.failure_reason);
      break;
    case 'subscription.cancelled':
      if (data.cancellation_type === 'regret') await acesso.bloquearAgora(conta);
      else await acesso.liberarAte(conta, data.current_period_end);
      break;
    case 'subscription.expired':
      await acesso.bloquearAgora(conta);
      break;
  }
  await eventos.marcarProcessado(id);
});
```

| Evento | Quando chega | Ação na Agenda Clara |
| - | - | - |
| `subscription.created` | Assinatura criada | Registrar |
| `subscription.activated` | Primeira cobrança aprovada, inclusive depois de uma análise; no trial grátis, já na criação, sem o objeto `charge` | Liberar acesso |
| `subscription.renewed` | Cobrança do ciclo aprovada, inclusive a primeira cheia após o trial | Estender acesso até `current_period_end` |
| `subscription.payment_failed` | Cada tentativa de cobrança recusada, inclusive a primeira | Avisar o cliente; manter acesso |
| `subscription.cancelled` | Assinatura cancelada | `regret`: bloquear o acesso imediatamente. `regular`: manter até `current_period_end` |
| `subscription.expired` | Retentativas esgotadas ou plano chegou ao `endDate` | Bloquear acesso |

> [!NOTE]
>
> Os eventos `subscription.trial_started` e `subscription.trial_ended` existem no contrato de tipos, mas **não são entregues** hoje. Acompanhe o trial pelos eventos `subscription.activated` e `subscription.renewed`, que trazem o objeto `trial`.

**8. Acompanhe renovações e retentativas**

O ciclo fica ancorado na data e hora da contratação. Com trial, a referência passa a ser o fim do trial, quando a primeira mensalidade é cobrada. No plano mensal, o dia de referência é mantido: uma contratação 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 (`current_period_end`). O novo período começa exatamente no fim do anterior, então esse intervalo de algumas horas não desloca o ciclo. Se a cobrança for recusada:

* as rodadas seguintes tentam de novo;
* cada recusa gera `subscription.payment_failed`, com `failure_reason` em texto (ex.: `"Cartão vencido"`);
* ao atingir o limite de tentativas do ciclo, a assinatura vira `expired` e chega `subscription.expired`.

O calendário exato das retentativas e o limite por ciclo estão em [Ciclo de vida](https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md).

Para ver o histórico, consulte a assinatura:

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

A resposta traz `charges`, com uma linha por tentativa, do ciclo mais recente para o mais antigo. Cada linha tem `billingCycle`, valor e status (`pending`, `paid`, `failed` ou `refunded`). As retentativas recusadas de um ciclo repetem o mesmo `billingCycle`, e `billingCycle: 0` é a cobrança do trial pago.

> [!NOTE]
>
> O `charges[].id` é o id do registro de cobrança da assinatura (o mesmo valor de `data.charge.id` nos webhooks de assinatura). Ele não funciona em `GET /v1/charges/{id}`. O id da cobrança aparece em `firstCharge.chargeId` e `trialCharge.chargeId` na criação, em `data.charge.charge_id` nos webhooks de assinatura e em `data[].chargeId` na listagem `GET /v1/subscription-plans/{id}/charges`.

**9. Troque de plano ou de cartão**

A assinatura não permite trocar plano, cartão ou valor, nem pausar. Só `metadata` pode ser alterado, e só em assinatura `active`. Para o cliente que sobe do Essencial para o Equipe, a Agenda Clara:

1. cancela a assinatura atual com `POST /v1/subscriptions/{id}/cancel`;
2. cria uma assinatura nova no plano Equipe, com `skipTrial: true` para não dar outro período grátis.

```json theme={null}
{
  "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R",
  "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "cardTokenId": "2RhQgK4vN8pT1wZ6yB3mC7dF",
  "skipTrial": true,
  "metadata": { "contaAgendaClara": "AC-55821", "trocaDe": "essencial" }
}
```

A nova assinatura começa um ciclo novo, com cobrança imediata do valor cheio. A Finvia não calcula valor proporcional: se quiser compensar dias já pagos no plano antigo, faça isso na sua política comercial.

> [!WARNING]
>
> Se a troca acontecer **nos primeiros 7 dias** da assinatura antiga, o cancelamento entra como arrependimento (`regret`) e estorna automaticamente todas as cobranças pagas dela. Considere isso antes de trocar o plano de um cliente recém-contratado.

**10. Cancele quando o cliente pedir**

```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": "Cliente encerrou o salão" }'
```

`reason` é opcional, com no máximo 500 caracteres. O resultado depende do prazo, contado em dias completos desde a criação da assinatura. É uma regra da plataforma, aplicada a todo cancelamento, venha ele de você ou da Finvia:

| Quando | `cancellationType` | Estorno | Acesso |
| - | - | - | - |
| Até 7 dias da criação | `regret` | Todas as cobranças pagas são estornadas (`refunded: true`; `false` se não havia cobrança paga, como no trial grátis, ou se um estorno não foi concluído) | Revogado imediatamente |
| Depois de 7 dias | `regular` | Nenhum (`refunded: false`) | O status já é `cancelled` e as cobranças param. `accessRevokedAt` indica até quando o acesso pago vale, e a Agenda Clara controla esse prazo |

Não existe opção para cancelar nos primeiros 7 dias sem estornar. Cancelar uma assinatura já cancelada ou expirada retorna `400` "Subscription already cancelled or expired".

## Regras e cuidados

> [!WARNING]
>
> **Não use cartão salvo em `POST /v1/charges` para cobrar todo mês.** Nessa rota, o CVV do comprador é obrigatório a cada cobrança, então ela não cobra com o cliente ausente. A cobrança recorrente automática é feita pelas assinaturas.

* **Permissão da chave.** Desenvolvedor e Financeiro recebem `403` em todas as rotas de planos e assinaturas; Visualizador só nas consultas.
* **Moeda.** Planos cobrados no cartão aceitam só `BRL`.
* **Trial grátis valida com R\$ 1,00.** A cobrança é real, também com a chave de teste. O cliente pode ver a cobrança e o estorno na fatura. Avise no checkout.
* **`pending_activation` não cobra nem renova.** Se a análise aprovar o pagamento, a assinatura passa a `active` sozinha. Se a cobrança foi recusada, crie uma nova assinatura. Não crie outra enquanto `firstCharge.pending` for `true`.
* **Acesso no cancelamento regular é sua responsabilidade.** A Finvia para de cobrar imediatamente e informa a data limite em `accessRevokedAt` (e em `current_period_end` no webhook).
* **`failure_reason` é texto.** Use para exibir ou registrar, nunca para decidir o fluxo.
* **Correlação com cobranças.** Cada cobrança paga da assinatura também gera `charge.created` e `charge.paid`. No evento de assinatura, `data.charge.charge_id` é o ID da cobrança (o mesmo de `GET /v1/charges/{id}`). No `charge.paid`, o `metadata` traz `subscription_id` e `billing_cycle`.
* **Recusa não gera `charge.*`.** A falha de uma cobrança de assinatura é avisada só por `subscription.payment_failed`.
* **Sem split.** As cobranças recorrentes das assinaturas não recebem split. Se um parceiro tiver direito a parte da mensalidade, o repasse precisa ser feito por outro caminho.

## Variações do caso

> [accordion] E se a empresa quiser plano anual?
>
> O contrato oferece `weekly`, `biweekly`, `monthly` e `custom`. Um plano anual usa `recurrenceType: "custom"` com `recurrenceInterval`, um número inteiro de **dias** corridos (por exemplo, `365`). O `custom` só soma dias, então "a cada 365 dias" desliza um dia no calendário em anos bissextos. Nos tipos `weekly`, `biweekly` e `monthly`, `recurrenceInterval` é ignorado.

> [accordion] E se o cliente não quiser cartão?
>
> As assinaturas cobram só no cartão. Para quem paga por Pix, o sistema da Agenda Clara pode gerar todo mês uma cobrança Pix avulsa com `POST /v1/charges` e controlar o acesso pelo `charge.paid`. O desenho está em [Educação e mensalidades](https://docs.fastpaybrasil.com/casos-de-uso/educacao-mensalidades.md), na variação de Pix mensal.

> [accordion] E se a empresa quiser criar a assinatura em uma chamada só?
>
> Dá para enviar o objeto `customer` (com `name`, `email` e `document` do tipo `cpf` ou `cnpj`) e o cartão em `paymentMethod` direto em `POST /v1/subscriptions`. A API localiza o cliente pelo e-mail ou cria um novo, e registra o cartão. Se já existir um cliente com o mesmo e-mail, vale o documento do cadastro dele, e não o da requisição. Use `customerId` **ou** `customer`, e `cardTokenId` **ou** `paymentMethod`, nunca os dois.

> [accordion] E se a empresa quiser escolher o dia da cobrança?
>
> Hoje não é possível escolher o dia de cobrança. O ciclo fica ancorado na data da contratação (ou no fim do trial), e o campo `billingDay` não existe mais: se for enviado, é ignorado sem erro. Para alinhar o ciclo a um dia do mês, crie a assinatura nesse dia.

> [accordion] E se o cartão do cliente vencer?
>
> A tentativa chega como `subscription.payment_failed`, e `charge.charge_id` pode vir `null` quando a tentativa nem foi enviada à cobrança (cartão vencido ou indisponível). Essa tentativa conta para o limite. Peça um cartão novo, registre-o, cancele a assinatura atual e crie outra.

## Checklist de implementação

* [ ] Chave gerada por Owner ou Manager (Desenvolvedor e Financeiro recebem `403` nas assinaturas)
* [ ] Planos criados em `BRL`, com o trial definido, e `id` lido da resposta `201`
* [ ] Cliente cadastrado com e-mail e CPF ou CNPJ
* [ ] Cartão registrado com `POST /v1/cards` e `status` `active`
* [ ] Aviso no checkout sobre a validação de R\$ 1,00 no trial grátis
* [ ] Tratamento de `active`, `pending_activation`, `firstCharge.pending` e dos códigos `CARD_VALIDATION_FAILED`, `CARD_VALIDATION_IN_PROGRESS` e `CARD_VALIDATION_RATE_LIMITED`
* [ ] Nova assinatura criada para tentar de novo depois de uma primeira cobrança recusada
* [ ] Endpoint de webhook com idempotência persistente pelo `id` do evento
* [ ] Acesso liberado em `activated` e `renewed`, bloqueado em `expired` e no cancelamento `regret`
* [ ] Acesso mantido até `current_period_end` no cancelamento `regular`
* [ ] Comunicação ao cliente a cada `subscription.payment_failed`
* [ ] Troca de plano feita com cancelamento e nova assinatura, considerando a janela de 7 dias
* [ ] Homologação com cartão real de valor baixo e cancelamento no mesmo dia

## Como homologar

Os cenários SUB-01 a SUB-06 cobrem o fluxo: registrar cartão, cobrança com cartão salvo, criar plano, criar assinatura, receber `subscription.created` e `subscription.activated` e cancelar em até 7 dias conferindo `cancellationType: "regret"` e `refunded: true`. Com a chave de teste, a cobrança com cartão salvo (SUB-02) é simulada, mas o cadastro do cartão e as assinaturas são reais: use cartão real com valor baixo e cancele no mesmo dia. Detalhes no [roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md).

## Veja também

> [card] [Planos](https://docs.fastpaybrasil.com/guias/assinaturas/planos.md)
>
> Recorrência, trial e desativação de planos.

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

> [card] [Webhooks de assinatura](https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md)
>
> Payload de cada evento.

> [card] [Criar assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/criar.md)
>
> Referência completa da rota.


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