Implementar este caso com um assistente de IA
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:O que a Finvia resolve
Arquitetura da solução
pending_activation, como mostra o passo “Trate a resposta da criação”.
Passo a passo
Confira o perfil de quem gera a chave
403 Acesso negado em todas as rotas de planos e assinaturas, e o perfil Visualizador só acessa as consultas.Crie os planos
BRL. O merchantId é o ID da sua conta na Finvia.201 traz só o id do plano. Para ver o plano completo, use GET /v1/subscription-plans/{id}. Repita para Essencial e Rede.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.Cadastre o cliente
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.Registre o cartão (cards-first)
active, sem transação de teste e sem etapa de ativação.Crie a assinatura
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 }.Trate a resposta da criação
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.Controle o acesso pelos webhooks
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.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.Acompanhe renovações e retentativas
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, comfailure_reasonem texto (ex.:"Cartão vencido"); - ao atingir o limite de tentativas do ciclo, a assinatura vira
expirede chegasubscription.expired.
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.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.Troque de plano ou de cartão
metadata pode ser alterado, e só em assinatura active. Para o cliente que sobe do Essencial para o Equipe, a Agenda Clara:- cancela a assinatura atual com
POST /v1/subscriptions/{id}/cancel; - cria uma assinatura nova no plano Equipe, com
skipTrial: truepara não dar outro período grátis.
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:400 “Subscription already cancelled or expired”.Regras e cuidados
- Permissão da chave. Desenvolvedor e Financeiro recebem
403em 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_activationnão cobra nem renova. Se a análise aprovar o pagamento, a assinatura passa aactivesozinha. Se a cobrança foi recusada, crie uma nova assinatura. Não crie outra enquantofirstCharge.pendingfortrue.- Acesso no cancelamento regular é sua responsabilidade. A Finvia para de cobrar imediatamente e informa a data limite em
accessRevokedAt(e emcurrent_period_endno 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.createdecharge.paid. No evento de assinatura,data.charge.charge_idé o ID da cobrança (o mesmo deGET /v1/charges/{id}). Nocharge.paid, ometadatatrazsubscription_idebilling_cycle. - Recusa não gera
charge.*. A falha de uma cobrança de assinatura é avisada só porsubscription.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
E se a empresa quiser plano anual?
E se a empresa quiser plano anual?
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.E se o cliente não quiser cartão?
E se o cliente não quiser cartão?
POST /v1/charges e controlar o acesso pelo charge.paid. O desenho está em Educação e mensalidades, na variação de Pix mensal.E se a empresa quiser criar a assinatura em uma chamada só?
E se a empresa quiser criar a assinatura em uma chamada só?
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.E se a empresa quiser escolher o dia da cobrança?
E se a empresa quiser escolher o dia da cobrança?
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.E se o cartão do cliente vencer?
E se o cartão do cliente vencer?
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
403nas assinaturas) - Planos criados em
BRL, com o trial definido, eidlido da resposta201 - Cliente cadastrado com e-mail e CPF ou CNPJ
- Cartão registrado com
POST /v1/cardsestatusactive - Aviso no checkout sobre a validação de R$ 1,00 no trial grátis
- Tratamento de
active,pending_activation,firstCharge.pendinge dos códigosCARD_VALIDATION_FAILED,CARD_VALIDATION_IN_PROGRESSeCARD_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
iddo evento - Acesso liberado em
activatederenewed, bloqueado emexpirede no cancelamentoregret - Acesso mantido até
current_period_endno cancelamentoregular - 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, recebersubscription.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.

