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 primeiro pagamento
  • trialing: Assinatura em período de trial gratuito
  • active: Assinatura ativa com pagamentos sendo processados
  • 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 ciclos 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 cycles 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 gerados cycles 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 Pagamentos

​
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 do ciclo)
  • D+1: 1ª retentativa
  • D+4: 2ª retentativa
  • D+9: 3ª retentativa
  • D+16: 4ª retentativa (última tentativa)
Se todas as retentativas falharem, o ciclo fica failed, e a assinatura ficará unpaid. A assinatura permanecerá neste estado e continuará tentando cobrar nos próximos ciclos até que seja cancelada manualmente.

​
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 pagamento falharam:
  • cancelAfterAllRetries = false (padrão): A assinatura vai para status unpaid e continuará tentando cobrar nos próximos cycles
  • cancelAfterAllRetries = true: A assinatura é automaticamente cancelada e não processará mais pagamentos
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 ciclos já cobrados.

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 um ciclo já iniciado, somente ciclos futuros são afetados.