Para o negócio: três regras resumem a operação. Primeiro, quando o cartão é recusado na renovação, a Finvia tenta de novo por alguns dias antes de encerrar a assinatura. Segundo, não há troca de cartão nem de plano: o cliente cancela e assina de novo, com cobrança imediata. Terceiro, pela regra da plataforma, cancelamentos em até 7 dias da criação da assinatura estornam automaticamente tudo o que foi pago; depois disso, não há estorno e o acesso vale até o fim do período pago.
Status da assinatura
cancelled e expired são estados finais. Para o cliente voltar a assinar, crie uma nova assinatura.
O desenho abaixo mostra como a assinatura passa de um status para outro e o aviso que acompanha cada mudança.
Assinatura parada em pending_activation
A rotina de cobrança só processa assinaturas active. Uma assinatura pending_activation não é cobrada de novo, não renova e não expira sozinha. Ela só sai desse status em um caso: a primeira cobrança (ou a do trial pago) ficou em análise (firstCharge.pending: true ou trialCharge.pending: true) e a análise aprovou. Aí ela passa a active e chega subscription.activated. Se a análise recusar, chega subscription.payment_failed e ela continua parada. PATCH /v1/subscriptions/{id} também não destrava, porque só aceita assinaturas active.
Para tentar de novo pela API (por exemplo, com outro cartão), crie uma nova assinatura com POST /v1/subscriptions. A API não reaproveita a pendente: a nova tem outro id. Cancele a pendente com POST /v1/subscriptions/{id}/cancel para que ela não fique na listagem; enquanto estiver pendente, ela não cobra nada.
Como funciona
1
Criação e ativação
A assinatura nasce
active quando a primeira cobrança é aprovada (ou o trial começa). Se a primeira cobrança é recusada ou fica em análise, ela fica em pending_activation.2
Renovação a cada ciclo
Uma rotina roda às 6h, 12h e 18h (horário de Brasília) e cobra as assinaturas cujo período terminou. Com sucesso, chega
subscription.renewed.3
Retentativas em caso de falha
Se a renovação for recusada, as rodadas seguintes tentam de novo. Cada recusa gera
subscription.payment_failed.4
Encerramento
A assinatura termina por cancelamento (
cancelled) ou por expiração (expired), quando as tentativas se esgotam ou o plano chega ao endDate.Ciclo de cobrança e renovação
Não há como escolher o dia da cobrança. O ciclo segue estas regras:
Exemplo: uma assinatura mensal contratada em 15/01 às 10h30 cobre o período até 15/02 às 10h30. A renovação sai na rodada das 6h de 16/02, e o novo período vai de 15/02 às 10h30 até 15/03 às 10h30.
Em validação (V-34): o time Finvia ainda confirma a cobrança no “dia seguinte” ao fim do período e o limite de 12 tentativas antes da publicação.
Retentativa de cobrança
Quando a cobrança de renovação é recusada, a Finvia tenta de novo automaticamente:
Um plano com
endDate também encerra a assinatura em expired quando o período seguinte começaria depois dessa data.
O desenho abaixo mostra a renovação de um ciclo, com as novas tentativas quando o cartão é recusado.
O dia seguinte e o limite de 12 tentativas estão em validação (V-34), como indicado acima.
Enquanto houver retentativas pendentes, a assinatura continua
active. Use o subscription.payment_failed para avisar o comprador a atualizar o cartão. Como não existe troca de cartão na assinatura, o caminho é cancelar e criar outra (veja Trocar cartão ou plano).Para o negócio: a janela de retentativas é a oportunidade de recuperar o assinante. Uma régua de comunicação comum é avisar na primeira falha (“tivemos um problema com o seu cartão”) e reforçar perto do fim das tentativas, com um link para o cliente assinar de novo com outro cartão.
Atualizar a assinatura
Apenasmetadata pode ser atualizado, e só em assinaturas active.
cURL
200:
Trocar cartão ou plano
1
Registre o novo cartão (se for troca de cartão)
POST /v1/cards com os dados do novo cartão.2
Cancele a assinatura atual
POST /v1/subscriptions/{id}/cancel. Atenção à regra de 7 dias explicada abaixo.3
Crie a nova assinatura
POST /v1/subscriptions com o novo cardTokenId ou o novo subscriptionPlanId. A primeira cobrança acontece imediatamente.Para o negócio: na troca, o cliente paga a nova assinatura imediatamente, mesmo que ainda tenha dias do período anterior. Se a troca acontece depois de 7 dias da contratação, não há estorno automático da assinatura antiga. Defina a sua política (por exemplo, conceder dias extras ou fazer a troca perto da data de renovação) e comunique ao cliente antes.
Cancelamento
cURL
reason aceita até 500 caracteres.
A API trata o cancelamento de duas formas, conforme a data de criação da assinatura. O cancelamento em até 7 dias da criação estorna automaticamente as cobranças pagas e vem com cancellationType igual a regret (arrependimento):
O desenho abaixo mostra o que acontece em cada tipo de cancelamento.
Regra dos 7 dias
Regra da plataforma: se a assinatura for cancelada em até 7 dias da criação, todas as cobranças pagas dela são estornadas automaticamente e o acesso é encerrado na hora. Depois desse prazo, o cancelamento não gera estorno e o acesso continua até o fim do período pago.- A regra é automática para todo cancelamento dentro da janela, venha ele do lojista ou da Finvia, por qualquer motivo. Ela não depende de pedido do comprador e vale também para venda entre empresas.
- A janela conta a partir da criação da assinatura, e não da entrega do produto ou serviço nem da primeira cobrança.
- A contagem é em dias completos: um cancelamento feito até 7 dias e 23 horas depois da criação ainda é
regret. - Não existe opção para cancelar dentro da janela sem estornar.
Em validação (V-51): o jurídico da Finvia decide se esta página cita a base legal (art. 49 do CDC) e com que ressalva.
Arrependimento (até 7 dias)
refundId identifica o estorno (pode ser null). accessRevokedAt indica quando o acesso foi revogado.
Cancelamento regular (depois de 7 dias)
accessRevokedAt é só a data até a qual o acesso do comprador vale (fim do período já pago). O status já é cancelled e as cobranças pararam. É a sua plataforma que mantém o acesso até essa data e o encerra depois.
Histórico de cobranças
A consulta da assinatura por ID traz o histórico de tentativas de cobrança emcharges. Há uma linha por tentativa: as retentativas recusadas de um ciclo repetem o mesmo billingCycle. A lista vem ordenada por billingCycle decrescente, e billingCycle: 0 é a cobrança do trial pago.
cURL
Status das cobranças da assinatura
charges[].id é o id do registro de cobrança da assinatura (igual a data.charge.id nos webhooks de assinatura) e não funciona em GET /v1/charges/{id}. O id da cobrança vem em firstCharge.chargeId e trialCharge.chargeId na criação, em data.charge.charge_id nos webhooks e em data[].chargeId na listagem de cobranças do plano (GET /v1/subscription-plans/{id}/charges), que traz também id, subscriptionId e billingCycle. Veja Consultar assinatura.Listar assinaturas
GET /v1/subscriptions é paginada e aceita os filtros merchantId, customerId, status (pending_activation, active, cancelled, expired), search (nome ou e-mail do cliente, ou nome do plano), page (padrão 1) e size (padrão 10).
cURL
Webhooks do ciclo de vida
Cada cobrança de assinatura paga também dispara
charge.created e charge.paid. A recusa de uma cobrança de assinatura não dispara webhook charge.* de recusa: quem avisa é o subscription.payment_failed. Payloads completos em Webhooks de assinatura.
Boas práticas
- Valide o plano antes do checkout. Consulte
GET /v1/subscription-plans/{id}e confirme que o plano estáactive. - Trate falha na primeira cobrança. Se a resposta da criação vier com
status: "pending_activation"efirstCharge.success: false, ofereça ao cliente tentar de novo com outro cartão, criando uma nova assinatura, e cancele a pendente. - Não duplique em caso de análise. Se
firstCharge.pendingviertrue, o pagamento está em análise. Não crie outra assinatura: aguardesubscription.activated(aprovado) ousubscription.payment_failed(recusado). - Avise o cliente sobre a renovação. Envie um lembrete alguns dias antes da cobrança automática.
- Trate cartão vencido ou recusado. A cada tentativa que falha chega
subscription.payment_failed. Oriente o cliente a cancelar e criar outra assinatura com o novo cartão. - Use
metadata. Guarde dados que ligam a assinatura ao seu sistema:
Erros comuns
Perguntas frequentes
Quantas vezes a Finvia tenta cobrar um cartão recusado?
Quantas vezes a Finvia tenta cobrar um cartão recusado?
Hoje, até 12 tentativas recusadas no mesmo ciclo, nas rodadas das 6h, 12h e 18h (horário de Brasília), ao longo de cerca de 4 dias. No limite, a assinatura passa a
expired e chega subscription.expired.Posso pausar uma assinatura?
Posso pausar uma assinatura?
Não. Não há pausa. A alternativa é cancelar e, quando o cliente quiser voltar, criar uma nova assinatura.
O cliente cancelou no 5º dia. O que acontece com o dinheiro?
O cliente cancelou no 5º dia. O que acontece com o dinheiro?
Pela regra da plataforma, é um cancelamento por arrependimento (
regret): todas as cobranças pagas são estornadas automaticamente e o acesso é encerrado na hora. Confira refunded: true na resposta.O cliente cancelou no 20º dia de um plano mensal. Ele perde o acesso imediatamente?
O cliente cancelou no 20º dia de um plano mensal. Ele perde o acesso imediatamente?
Não deveria. O status vira
cancelled e as cobranças param, mas o acesso vale até accessRevokedAt, o fim do período já pago. Quem controla isso é a sua plataforma.Assinatura expirada pode ser reativada?
Assinatura expirada pode ser reativada?
Não.
expired é um estado final. Crie uma nova assinatura para o cliente.Como testar
Veja também
Assinaturas: visão geral
Como criar assinaturas.
Planos
Preço, recorrência e trial.
Webhooks de assinatura
Payloads de cada evento.
Cancelar assinatura
Contrato completo da rota.

