Status da Recorrência

O que é: RecurrentPaymentStatus (também referenciado como recurrentPaymentStatusEnum) é o campo que indica o estado atual de um pagamento recorrente no Checkout Cielo.

• Onde aparece:
  • Na resposta da consulta de recorrência (GET), no campo RecurrentPaymentStatus.
  • No conteúdo das notificações de finalização da transação, como campo recurrent_status.
• O que representa: representa a fase do ciclo de vida de uma recorrência — desde o estado inicial (antes do primeiro pagamento) até os estados finais de encerramento (por ação do usuário, por prazo atingido ou por falhas técnicas).

Tabela de status da recorrência

Como usar

O campo RecurrentPaymentStatus deve ser monitorado para acompanhar o ciclo de vida de uma recorrência:

1. Consulta direta: use o endpoint GET /RecurrentPayment/{id} com o PagadorRecurrentPaymentId para obter o status atual da recorrência.
2. Notificações: o campo recurrent_status é retornado no conteúdo das notificações de finalização da transação.
3. Encerramento automático: quando o status for 2 (Negada), 5 (Cartão expirado) ou 6 (Máximo de tentativas), o sistema desativou a recorrência e ela não será mais executada. Nenhuma reativação é possível.
4. Desativação manual: use o endpoint DELETE /RecurrentPayment/Deactivate/{pagadorRecurrentPaymentId} para encerrar uma recorrência ativa (status 1). Essa ação é irreversível.
5. Atualização: enquanto ativa (status 1), é possível atualizar valor, intervalo, data de encerramento, dia de cobrança e próxima data de pagamento via PUT /RecurrentPayment/Update.

Importante: operações de consulta detalhada, atualização e desativação só estão disponíveis após o pagamento da primeira transação, quando o PagadorRecurrentPaymentId é gerado.

Interpretação dos valores

• Ativo / em andamento

  • 1 — Ativa: a recorrência está funcionando normalmente. Cobranças ocorrem conforme o intervalo configurado (mensal, bimensal, trimestral, semestral ou anual) e podem ser gerenciadas via API.

• Transitórios / aguardando

  • 0 — Pendente: estado inicial após a criação da recorrência, antes que o primeiro pagamento seja processado. O PagadorRecurrentPaymentId ainda não está disponível.
  • 7 — Aguardando conciliação: estado intermediário durante o processo de conciliação financeira.

• Encerrado automaticamente pelo sistema

  • 2 — Negada: o emissor recusou a cobrança e o sistema desativou a recorrência.
  • 5 — Desativado por cartão expirado: o cartão vinculado atingiu a data de validade e a recorrência foi encerrada.
  • 6 — Desativado por número máximo de tentativas: limite de tentativas de cobrança atingido sem sucesso. A recorrência é encerrada definitivamente.

• Encerrado intencionalmente

  • 3 — Desativado pelo usuário.
  • 4 — Finalizada: a recorrência alcançou a EndDate configurada e foi encerrada ao término do contrato.

Observações importantes

• Uma vez desativada (status 2, 3, 4, 5 ou 6), a recorrência não pode ser reativada. Para retomar cobranças periódicas, é necessário criar uma nova recorrência.
• O PagadorRecurrentPaymentId é gerado apenas no pagamento da primeira transação. Antes disso (status 0), operações de atualização e desativação não estão disponíveis.
• A recorrência no Checkout Cielo é exclusiva para cartão de crédito.
• Os intervalos de cobrança disponíveis são: Mensal (1 mês), Bimestral (2 meses), Trimestral (3 meses), Semestral (6 meses) e Anual (12 meses).