Implementar este caso com um assistente de IA
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
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 A resposta
403 Acesso negado nas rotas de planos e assinaturas.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
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 O filtro aceita
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: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.7
Cancele quando o aluno sair
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
- 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.
monthlysegue o ciclo a partir da contratação. O intervalocustomconta 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ó porsubscription.payment_failed. Cada mensalidade paga gera tambémcharge.createdecharge.paid, comsubscription_idebilling_cyclenometadata. - Permissão da chave. Chaves geradas por usuários Desenvolvedor ou Financeiro recebem
403em 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
Pix mensal para quem não usa cartão
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: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.E o material didático do semestre?
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).E se a escola tiver várias unidades com CNPJ próprio?
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.
E se a escola der desconto para irmãos?
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, comendDateno fim do ano letivo - Responsável financeiro cadastrado com e-mail e CPF
- Cartão registrado e com
statusactive - Assinatura criada com
metadatado aluno e da turma - Tratamento de
active,pending_activationefirstCharge.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
statuspaidconfirmado 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.

