Skip to main content
Depois de criada, a assinatura passa por renovações, eventuais falhas de cobrança e, em algum momento, termina por cancelamento ou expiração. Esta página explica cada etapa, o que a Finvia faz sozinha e o que a sua plataforma precisa controlar.
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.
Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste. Veja como homologar em Assinaturas: visão geral.

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

Apenas metadata pode ser atualizado, e só em assinaturas active.
cURL
Resposta 200:

Trocar cartão ou plano

Não existe troca de cartão, troca de plano, alteração de valor nem pausa. Para trocar o cartão ou o plano, cancele a assinatura e crie outra. A nova assinatura começa um ciclo novo, com cobrança imediata.
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
O corpo é opcional. O campo 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.
No cancelamento por arrependimento, confira refunded. Se vier false numa assinatura que tinha cobrança paga, um estorno não foi concluído e o valor ainda não voltou ao cliente. Acompanhe pelo histórico da assinatura ou acione o suporte da Finvia.

Cancelamento regular (depois de 7 dias)

No cancelamento regular, 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.
Para o desenvolvedor: ao receber a resposta do cancelamento (ou o webhook subscription.cancelled), grave accessRevokedAt no seu sistema e agende o bloqueio do acesso para essa data. No caso regret, bloqueie imediatamente.

Histórico de cobranças

A consulta da assinatura por ID traz o histórico de tentativas de cobrança em charges. 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
Para o desenvolvedor: antes de criar uma assinatura, consulte se o cliente já tem uma active no mesmo plano com GET /v1/subscriptions?customerId=...&status=active. Isso evita assinaturas duplicadas quando o cliente clica duas vezes ou volta ao checkout.

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

  1. Valide o plano antes do checkout. Consulte GET /v1/subscription-plans/{id} e confirme que o plano está active.
  2. Trate falha na primeira cobrança. Se a resposta da criação vier com status: "pending_activation" e firstCharge.success: false, ofereça ao cliente tentar de novo com outro cartão, criando uma nova assinatura, e cancele a pendente.
  3. Não duplique em caso de análise. Se firstCharge.pending vier true, o pagamento está em análise. Não crie outra assinatura: aguarde subscription.activated (aprovado) ou subscription.payment_failed (recusado).
  4. Avise o cliente sobre a renovação. Envie um lembrete alguns dias antes da cobrança automática.
  5. 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.
  6. Use metadata. Guarde dados que ligam a assinatura ao seu sistema:

Erros comuns

Perguntas frequentes

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.
Não. Não há pausa. A alternativa é cancelar e, quando o cliente quiser voltar, criar uma nova assinatura.
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.
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.
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.