Para o negócio: estes eventos mantêm o acesso do assinante coerente com o pagamento.
subscription.renewed estende o acesso, subscription.payment_failed é a hora de avisar o cliente para trocar o cartão e subscription.expired encerra o acesso quando as tentativas de cobrança se esgotam. Também é por eles que a sua régua de comunicação (boas-vindas, aviso de falha, oferta de reativação) pode ser disparada automaticamente.Quando usar
Como funciona
O desenho abaixo mostra o que o seu sistema faz ao receber cada evento de assinatura. Cada cobrança de assinatura paga também geracharge.created e charge.paid. A recusa gera só o subscription.payment_failed.
1
Assinatura criada
Sua aplicação chama
POST /v1/subscriptions. A Finvia envia subscription.created.2
Ativação
Com a primeira cobrança aprovada (ou o início do trial), chega
subscription.activated.3
Renovações
A cada ciclo cobrado com sucesso, chega
subscription.renewed, com o número do ciclo em charge.billing_cycle.4
Falhas e retentativas
Se a cobrança de renovação falhar, cada tentativa malsucedida gera um
subscription.payment_failed. A assinatura continua active enquanto houver tentativas.5
Encerramento
Com o cancelamento chega
subscription.cancelled. Com as tentativas esgotadas ou o fim do plano chega subscription.expired.Eventos disponíveis
Os eventos
subscription.trial_started e subscription.trial_ended estão definidos no contrato de tipos, mas não são entregues atualmente. Não os implemente como ativos. Em planos com trial, acompanhe a ativação e a conversão pelos eventos subscription.activated e subscription.renewed, que trazem o objeto trial no payload.Status da assinatura
Regras de negócio
Relação com os webhooks de cobrança
Cada cobrança de assinatura paga também dispara os webhookscharge.created e charge.paid da cobrança correspondente. A recusa de uma cobrança de assinatura não dispara webhook charge.* de recusa: quem avisa é o subscription.payment_failed.
Para ligar os dois fluxos:
- Nos eventos de assinatura,
data.charge.charge_idé o ID da cobrança, o mesmo usado nos webhookscharge.*e emGET /v1/charges/{id}. Jádata.charge.idé o ID do registro de cobrança da assinatura, outro identificador. - No webhook
charge.paidde uma cobrança de assinatura, ometadatatrazsubscription_idebilling_cycle, o que permite a ligação no sentido inverso.
Envelope
Todos os webhooks de assinatura usam o envelope padrão, com campos em snake_case. Oid da raiz identifica o evento e é a chave da receita de deduplicação. Não use livemode para separar teste de produção: as assinaturas não têm modo de teste.
Campos base do objeto data
Presentes em todos os eventos:
Em planos com trial,
subscription.activated e subscription.renewed trazem também o objeto trial, com startDate, endDate e, depois da conversão, convertedAt. Esse objeto usa camelCase, diferente do resto do payload. metadata volta exatamente como você enviou.
Objeto customer
Objeto plan
Valores em reais (ex.: 99.9 para R$ 99,90):
Objeto charge
Presente em subscription.renewed e subscription.payment_failed, e em subscription.activated exceto no trial grátis (não há cobrança na ativação). Valores em reais.
Payloads por evento
subscription.created
Enviado logo após a criação da assinatura. Traz só os campos base.subscription.activated
Enviado quando a assinatura é ativada. O conteúdo muda conforme o plano:subscription.renewed
Enviado quando uma cobrança recorrente é processada com sucesso. A estrutura é igual à dosubscription.activated, com billing_cycle incrementado.
subscription.payment_failed
Enviado a cada tentativa de cobrança recorrente que falha. Trazfailure_reason no topo de data e o objeto charge com os detalhes da falha.
failure_reason é um texto descritivo (ex.: "Recusa do banco emissor", "Cartão vencido"). Use-o para exibir ou registrar, nunca para decidir o fluxo. charge.charge_id vem null só quando a tentativa nem chegou a ser enviada para cobrança (cartão vencido ou indisponível). Essa tentativa também conta para o limite de tentativas do ciclo.subscription.cancelled
Enviado quando a assinatura é cancelada. Trazcancelled_at, cancellation_type e refunded.
- Arrependimento (até 7 dias)
- Regular (após 7 dias)
No cancelamento regular, o status já é
cancelled e as próximas cobranças não acontecem. current_period_end indica até quando o acesso do comprador vale, e é a sua plataforma que controla o acesso até essa data.subscription.expired
Enviado quando a assinatura é encerrada por esgotar as retentativas de cobrança ou porque o plano chegou aoendDate. Traz só os campos base.
Ciclo de vida em eventos
O desenho abaixo mostra os status da assinatura e o evento que acompanha cada mudança. Nos rótulos das setas, os eventos aparecem sem o prefixosubscription..
cancelled e expired são estados finais. Para o cliente voltar, crie uma nova assinatura. Uma assinatura em pending_activation também não é cobrada de novo: para tentar outra vez, crie uma nova assinatura e, se quiser, cancele a pendente.
Passo a passo
Node.js
Erros comuns
Perguntas frequentes
O cliente teve o cartão recusado. A assinatura é cancelada imediatamente?
O cliente teve o cartão recusado. A assinatura é cancelada imediatamente?
Não. Ela continua
active enquanto houver retentativas, nas rodadas das 06h, 12h e 18h (horário de Brasília), até o limite descrito em Ciclo de vida da assinatura. Se todas falharem, ela vira expired e chega subscription.expired.Como o cliente troca o cartão de uma assinatura?
Como o cliente troca o cartão de uma assinatura?
Não existe troca de cartão na assinatura. O caminho é cancelar a assinatura atual e criar outra com o novo cartão. A nova começa um ciclo novo, com cobrança imediata. Veja Ciclo de vida da assinatura.
A validação de R$ 1,00 do trial grátis gera webhook?
A validação de R$ 1,00 do trial grátis gera webhook?
Não. A cobrança de validação e o estorno dela não geram webhooks. No trial grátis, o
subscription.activated chega na criação, sem o objeto charge.Até quando mantenho o acesso depois de um cancelamento regular?
Até quando mantenho o acesso depois de um cancelamento regular?
Até
current_period_end. O status já é cancelled e as cobranças pararam, mas o período pago continua valendo. Quem controla o acesso até essa data é a sua plataforma.Como sei de qual assinatura veio um charge.paid?
Como sei de qual assinatura veio um charge.paid?
O
metadata do charge.paid de uma cobrança de assinatura traz subscription_id e billing_cycle.Como testar
Veja também
Assinaturas: visão geral
Como a cobrança recorrente funciona.
Ciclo de vida da assinatura
Status, retentativa e cancelamento.
Webhooks de cobrança
Os eventos charge.* de cada cobrança.
Webhooks: visão geral
Destinos, formatos, entrega e deduplicação.

