Skip to main content
O motor de recorrência da Malga oferece uma API para você gerenciar suas assinaturas recorrentes de forma programática.

​
Ciclo de Vida das Assinaturas

O motor de recorrência gerencia automaticamente o ciclo de vida das suas assinaturas, desde a criação até a expiração. Entender como funciona esse fluxo é essencial para implementar corretamente as ações de gerenciamento.

​
Estados das Assinaturas

  • created: Assinatura criada, aguardando primeira cobrança
  • trialing: Assinatura em período de trial gratuito
  • active: Assinatura ativa com cobranças sendo processadas
  • paused: Assinatura pausada temporariamente
  • canceled: Assinatura cancelada manualmente
  • unpaid: Assinatura inadimplente (após falha de todas as retentativas, exceto se cancelAfterAllRetries estiver habilitado)
  • expired: Assinatura expirada (atingiu o limite de faturas configurado)

​
Sistema de Trials

O motor de recorrência suporta períodos de trial gratuito para assinaturas. Durante o trial, a assinatura fica no status trialing e não gera faturas de cobrança.

​
Características dos Trials

  • Período gratuito: Cliente pode usar o serviço sem ser cobrado
  • Status especial: Assinatura fica com status trialing durante o período
  • Sem cobrança: Não são geradas faturas de cobrança durante o trial
  • Transição automática: Ao expirar, transiciona automaticamente para created

​
Estados com Trial

​
Regras para Trials

  • ✅ Permitido: Cancelar a assinatura durante o trial
  • ❌ Não permitido: Pausar a assinatura durante o trial
  • ❌ Não permitido: Editar o campo trialEnd após criação
  • ⚠️ Automático: Transição para created quando o trial expira

​
Fluxo de Processamento de Cobranças

​
Regras de Retentativas

O motor de recorrência segue regras específicas para retentativas baseadas no tipo de assinatura:

​
Estratégia Unificada para Todos os Intervalos (5 tentativas)

Para weekly, monthly, quarterly e yearly:
  • D+0: Tentativa inicial (no vencimento da fatura)
  • D+1: 1ª retentativa
  • D+4: 2ª retentativa
  • D+9: 3ª retentativa
  • D+16: 4ª retentativa (última tentativa)
Se todas as retentativas falharem, a fatura fica failed, e a assinatura ficará unpaid. A assinatura permanecerá neste estado e continuará tentando cobrar nas próximas faturas até que seja cancelada manualmente.

​
Status das Faturas

Cada fatura de uma assinatura possui um status que indica seu estado atual no processo de cobrança:
  • scheduled: Fatura agendada para processamento futuro
  • pending: Fatura aguardando processamento de cobrança
  • authorized: Fatura processada com sucesso (estado final - não pode ser alterado)
  • failed: Fatura que falhou após todas as retentativas (estado final - não pode ser alterado)
  • retrying: Fatura em processo de retentativa após falha
  • canceled: Fatura “não faturada”, marcada quando a assinatura é pausada ou cancelada (estado final - não será processada)
Estados finais: Faturas com status authorized, failed ou canceled são estados finais e não podem ser alteradas ou processadas novamente pelo scheduler de cobranças. Faturas authorized e failed preservam o histórico de auditoria de cobranças já processadas ou falhas finais, enquanto canceled preserva o histórico de faturas que não foram faturadas devido a pausa ou cancelamento da assinatura.

​
Status do PaymentHistory(Cobrança)

Cada cobrança registrada no paymentHistory de uma fatura possui um status que indica o resultado da tentativa individual:
  • pending: Status inicial quando uma cobrança é criada
  • authorized: Cobrança bem-sucedida, atualizada quando o pagamento é autorizado com sucesso
  • failed: Cobrança que falhou, atualizada quando o pagamento não foi autorizado
Importante: O PaymentHistory representa tentativas individuais de pagamento e possui apenas 3 status possíveis (pending, authorized, failed).

​
Ações Disponíveis por Estado

EstadoPausarRetomarCancelar
created❌❌✅
trialing❌❌✅
active✅❌✅
paused❌✅✅
canceled❌❌❌
unpaid❌❌✅
expired❌❌❌

​
Transições de Estado

​
Lógica de Falha após Retentativas

O estado FailureDecision representa o ponto de decisão quando todas as tentativas de cobrança falharam:
  • cancelAfterAllRetries = false (padrão): A assinatura vai para status unpaid e continuará tentando cobrar nas próximas faturas
  • cancelAfterAllRetries = true: A assinatura é automaticamente cancelada e não processará mais cobranças
Esta configuração é definida no Client Settings e se aplica a todas as assinaturas do cliente.

​
Operações de Gerenciamento

Atualizar uma assinatura

Atualize uma assinatura recorrente com os métodos de pagamento disponíveis na Malga.Ao alterar cycles, o novo valor não pode ser menor do que a quantidade de faturas já cobradas.

Pausar uma assinatura

Pause uma assinatura recorrente.

Políticas de Retentativa

Configure regras de retentativa personalizadas para suas assinaturas.

Configurar Webhooks

Configure notificações em tempo real sobre mudanças de status.

Retomar Assinatura

Retomar uma assinatura recorrente.

Cancelar Assinatura

Cancelar uma assinatura recorrente.
Pausar e cancelar não interrompem uma fatura já iniciada, somente faturas futuras são afetadas.Ao pausar ou cancelar uma assinatura, faturas pendentes (scheduled, pending, retrying) são marcadas como canceled (não faturado) para preservar o histórico de auditoria. Faturas já finalizadas (authorized, failed) não são alteradas.