Skip to main content
POST
Esta rota encerra a cobrança recorrente de uma assinatura. O efeito depende de quando o cancelamento acontece: em até 7 dias da criação, o cancelamento é do tipo arrependimento (regret) e estorna automaticamente todas as cobranças pagas; depois disso, as próximas cobranças não acontecem e não há estorno. A mesma rota é o primeiro passo para trocar o cartão ou o plano, já que a assinatura não aceita essas mudanças.
A janela de 7 dias é uma regra da plataforma e vale para todo cancelamento feito nela, venha do lojista ou da Finvia, por qualquer motivo, também em venda entre empresas. Ela conta a partir da criação da assinatura (não da primeira cobrança nem da entrega), 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.

Quando usar

Antes de chamar

  • Tenha uma chave secreta gerada por usuário com a permissão cancelar assinaturas. Nos perfis padrão, são Owner, Manager e Operador. Os perfis Visualizador, Desenvolvedor e Financeiro recebem 403 (veja Permissões por perfil).
  • A assinatura não pode estar cancelled nem expired. Nesses casos a resposta é 400.
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.

Tipos de cancelamento

Para o negócio: no cancelamento regular, a Finvia apenas para de cobrar: liberar ou bloquear o acesso ao serviço até accessRevokedAt é responsabilidade da sua plataforma. Defina essa regra com o time de produto antes de colocar o cancelamento no ar.

Parâmetros de caminho

string
required
Identificador único da assinatura. Ex.: 2RhQg9M7ZCg3X3nMb9W1kX8Q.

Corpo da requisição

O corpo é opcional.
string
Motivo do cancelamento. Máximo de 500 caracteres (maxLength 500). Ex.: Cliente solicitou cancelamento.

Respostas

A resposta 200 tem um de dois formatos, conforme o tipo de cancelamento.

Arrependimento (até 7 dias)

string
ID da assinatura.
string
Status da assinatura: cancelled.
string
Tipo de cancelamento: regret.
boolean
true quando havia cobranças pagas e todas foram estornadas. false quando não havia o que estornar (ex.: trial grátis) ou quando um estorno não foi concluído.
string | null
ID do estorno. Ex.: 2RhQg9M7ZCg3X3nMb9W1kX8Q.
string
Momento em que o acesso foi revogado (formato date-time).

Regular (depois de 7 dias)

string
ID da assinatura.
string
Status da assinatura: cancelled.
string
Tipo de cancelamento: regular.
boolean
false no cancelamento regular. (O contrato usa a mesma descrição do campo nas outras rotas: true só quando havia cobranças pagas e todas foram estornadas no arrependimento.)
string | null
Data até a qual o acesso do comprador continua valendo (fim do período pago), no formato date-time. O status já é cancelled e as cobranças já pararam: a sua plataforma mantém o acesso até essa data.
Depois do cancelamento, a Finvia envia o webhook subscription.cancelled, com cancelled_at, cancellation_type e refunded. Veja Webhooks de assinatura.
Para o desenvolvedor: decida o acesso pelo cancellationType. Com regret, revogue imediatamente. Com regular, guarde o accessRevokedAt e mantenha o acesso até essa data. Não use refunded para decidir o acesso: ele pode vir false também no arrependimento (trial grátis ou estorno não concluído).

Erros comuns

Veja também

Ciclo de vida

Status, renovação, retentativas e cancelamento.

Visão geral de assinaturas

Fluxo completo, do cliente à cobrança recorrente.

Planos

Recorrência, trial e status do plano.

Webhooks de assinatura

Payload do subscription.cancelled.

Registrar cartão

Registre o novo cartão antes de recriar a assinatura.

Homologação

Cenário SUB-06: cancelar dentro de 7 dias.