Skip to main content
As assinaturas cobram o cliente sozinhas, a cada ciclo, sem ninguém na tela. Os webhooks de assinatura são a forma de o seu sistema acompanhar isso: quando a assinatura começa, quando renova, quando uma cobrança falha e quando ela termina.
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 gera charge.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

Um cliente com cartão recusado pode gerar vários eventos subscription.payment_failed no mesmo ciclo, até três por dia. Se a sua aplicação envia um e-mail por evento, o cliente recebe vários e-mails em poucos dias. Controle a frequência dos avisos do seu lado, por exemplo um aviso por dia ou só na primeira e na última tentativa.

Relação com os webhooks de cobrança

Cada cobrança de assinatura paga também dispara os webhooks charge.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 webhooks charge.* e em GET /v1/charges/{id}. Já data.charge.id é o ID do registro de cobrança da assinatura, outro identificador.
  • No webhook charge.paid de uma cobrança de assinatura, o metadata traz subscription_id e billing_cycle, o que permite a ligação no sentido inverso.
Para o desenvolvedor: se você trata charge.paid e subscription.renewed, o mesmo pagamento chega duas vezes por caminhos diferentes. Escolha um deles como referência para estender o acesso (o subscription.renewed é o mais direto) e use o outro só para conciliação financeira, evitando estender o acesso duas vezes.

Envelope

Todos os webhooks de assinatura usam o envelope padrão, com campos em snake_case. O id 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 à do subscription.activated, com billing_cycle incrementado.

subscription.payment_failed

Enviado a cada tentativa de cobrança recorrente que falha. Traz failure_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. Traz cancelled_at, cancellation_type e refunded.
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 ao endDate. 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 prefixo subscription.. 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

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.
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.
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é 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.
O metadata do charge.paid de uma cobrança de assinatura traz subscription_id e billing_cycle.

Como testar

Assinaturas não têm sandbox: as cobranças são reais mesmo com a chave de teste. Veja como homologar em Assinaturas: visão geral.

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.