Skip to main content
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.
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.

Implementar este caso com um assistente de IA

Open in Cursor

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: 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

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

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.
O desenho abaixo mostra como a Escola Viva cobra a matrícula por Pix e a mensalidade por assinatura no cartão. Todo mês, a mensalidade segue um dos dois caminhos abaixo, conforme a forma de pagamento da família. 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.
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.
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.
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}.
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).
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

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. Cada falha gera subscription.payment_failed, e a assinatura continua active durante as retentativas.
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:
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.
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

O resultado segue uma regra da plataforma, aplicada a todo cancelamento e contada em dias completos desde a criação da assinatura: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

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

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:
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.
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).
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.
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

Detalhes e evidências no roteiro de homologação.

Veja também

Assinaturas

Planos, assinaturas e o fluxo cards-first.

Ciclo de vida

Retentativas, expiração e cancelamento.

SaaS por assinatura

O mesmo modelo com trial e troca de plano.

Cobrança por mensagem

Como enviar o Pix por WhatsApp ou e-mail.