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

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

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.
O desenho abaixo mostra quem faz o quê na assinatura da Agenda Clara, da criação dos planos ao controle de acesso. 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. 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.
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.
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.
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.
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.
O que acontece depende do trial do plano: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 }.
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

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.
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.Para ver o histórico, consulte a assinatura:
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.
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.
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.
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

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

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

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.
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, na variação de Pix mensal.
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.
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.
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.

Veja também

Planos

Recorrência, trial e desativação de planos.

Ciclo de vida da assinatura

Status, retentativas e cancelamento.

Webhooks de assinatura

Payload de cada evento.

Criar assinatura

Referência completa da rota.