Retry manual de pagamento

O retry manual tenta novamente um pagamento de renovação de assinatura com falha no momento em que você solicita, pela página de detalhes do pagamento ou pela API. Ele cobra o método de pagamento salvo na assinatura e é executado independentemente da programação de Payment Retries automáticos.

O que é o retry manual?

Quando um pagamento de renovação falha, a assinatura passa para on_hold e Payment Retries tenta cobrar novamente conforme uma programação de espera progressiva. Às vezes, você sabe que o pagamento será aprovado agora: o cliente confirmou que adicionou fundos à conta ou sua equipe de suporte está em uma ligação com ele. O retry manual permite enviar uma tentativa imediatamente, em vez de aguardar horas ou dias pela próxima tentativa programada.

Somente pagamentos de renovação: o retry manual se aplica a faturas de renovação de assinaturas enquanto a assinatura estiver em on_hold. Primeiros pagamentos, pagamentos avulsos, cobranças por alteração de plano e cobranças sob demanda não são elegíveis.
Nenhuma ação do cliente: a cobrança é enviada ao método de pagamento já salvo na assinatura.
Independente dos retries automáticos: um retry manual não consome uma tentativa da programação automática, não altera o próximo retry programado e funciona mesmo quando o Payment Retries está desativado.
Repete a fatura, não o pagamento: um pagamento com falha é apenas o ponto de entrada. O Dodo Payments localiza a fatura de renovação em aberto associada e cobra essa dívida; portanto, não importa a partir de qual pagamento com falha na fatura você inicia o retry.

Repetir pelo dashboard

Open the failed payment

Acesse Transactions → Payments e clique no pagamento de renovação com falha para abrir a página Transaction details.

Click Retry Payment Manually

Clique em Retry Payment Manually no canto superior direito. O botão fica disponível somente enquanto o pagamento estiver elegível.

Check the result

Um novo pagamento é criado para a tentativa e aparece no Activity Log. Se a cobrança for bem-sucedida, a assinatura retorna a active e a próxima data de cobrança avança normalmente. Se o processador de pagamentos ainda não tiver liquidado a cobrança, o pagamento será exibido como em andamento até que o webhook payment.succeeded ou payment.failed informe o resultado.

Página de detalhes da transação de um pagamento com falha mostrando o código e a mensagem de erro, um Activity Log e um botão Retry Payment Manually — Retry Payment Manually on the transaction details page of a failed renewal

Elegibilidade

Um retry manual só é enviado quando todas as verificações abaixo são aprovadas. A coluna Reason code corresponde ao que a API retorna: em reason em GET /payments/{payment_id}/retry e como o erro code em POST /payments/{payment_id}/retry.

Verificação	Requisito	Código do motivo
Tipo de pagamento	Um pagamento de renovação de assinatura cuja fatura ainda esteja aberta. Pagamentos sem fatura, primeiros pagamentos, pagamentos avulsos, cobranças por alteração de plano e cobranças sob demanda não podem ser repetidos.	`PAYMENT_NOT_RETRYABLE`
Status da assinatura	`on_hold`	`SUBSCRIPTION_INACTIVE`
Cancelamento programado	A assinatura não está programada para ser cancelada na próxima data de cobrança.	`CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION`
Método de pagamento salvo	A assinatura tem um método de pagamento salvo para cobrança.	`SUBSCRIPTION_HAS_NO_PAYMENT_METHOD`
Última falha	A falha mais recente é uma recusa flexível. Uma recusa definitiva ou uma falha sem código de erro classificado não pode ser repetida.	`MANUAL_RETRY_HARD_DECLINE`
Nada em andamento	Nenhum pagamento da fatura está em `processing` ou sem status registrado. Trata-se de uma tentativa, manual ou automática, que acabou de ser enviada e ainda não retornou um resultado. Aguarde primeiro o resultado.	`MANUAL_RETRY_IN_FLIGHT`
Pagamento mais recente com falha	O pagamento mais recente da fatura tem status `failed`. Um pagamento mais recente em qualquer outro estado que não seja `failed`, como `requires_customer_action`, `requires_payment_method` ou `cancelled`, impede o retry mesmo quando não há nada em andamento.	`PREVIOUS_PAYMENT_PENDING`
Ainda não pago	Nenhum pagamento da fatura foi concluído com sucesso.	`MANUAL_RETRY_ALREADY_PAID`
Limite de retries	Menos de 3 retries manuais enviados para a fatura e o período de espera já passou. Consulte Limites de retry.	`MANUAL_RETRY_LIMIT_REACHED`
Cliente	O cliente não está na sua blocklist.	`PAYMENT_NOT_RETRYABLE`
Conector de pagamento	Para assinaturas BYOP, o conector está habilitado.	`BYOP_CONNECTOR_DISABLED`
Modo live	No modo live, sua empresa habilitou pagamentos live.	`MERCHANT_NOT_LIVE`

O retry manual é mais restrito que os retries automáticos em um aspecto: ele exige que a assinatura esteja em on_hold. Os retries automáticos continuam sendo executados para outros status não ativos; consulte Transições de status da assinatura.

Repetir uma recusa definitiva no mesmo cartão não pode ser bem-sucedido, e recusas repetidas prejudicam sua taxa de autorização. Quando o motivo for MANUAL_RETRY_HARD_DECLINE, peça ao cliente que atualize o método de pagamento. O Subscription Dunning faz isso automaticamente.

Limites de retry

Cada fatura de renovação permite 3 retries manuais, com um período de espera entre eles:

Retry manual	Disponível
1	Assim que o pagamento for elegível
2	1 hora após o primeiro
3	3 horas após o segundo

Os limites se aplicam tanto ao modo de teste quanto ao modo live. Quando um retry é recusado por esse motivo, a API retorna MANUAL_RETRY_LIMIT_REACHED (HTTP 429). O corpo do erro contém apenas code e message. Para saber quando o próximo retry será liberado, consulte o estado do retry e leia retry_available_at. Ele é null quando os três retries já tiverem sido usados. Retries automáticos não contam para esse limite, e retries manuais não contam para as 8 tentativas da programação automática.

Retries manuais vs. automáticos

	Retry manual	Payment Retries
Acionador	Você, pelo dashboard ou pela API	Dodo Payments, conforme uma programação de espera progressiva
Momento	Imediatamente	12 horas após a falha, depois progressivamente mais tarde
Tentativas	3 por fatura, com períodos de espera de 1 hora e depois 3 horas	Até 8 por fatura, dentro da sua janela de recuperação
Requer Payment Retries habilitado	Não	Sim
Efeito sobre o outro	Nenhum. Uma falha manual não agenda nem move uma tentativa automática.	Nenhum. A sequência automática continua independentemente dos envios manuais.
Analytics	Contabilizado nas métricas de Payment retries na aba Recovery	Contabilizado nas mesmas métricas

Repetir pela API

Verifique primeiro a elegibilidade e depois envie o retry. Ambos os endpoints recebem o ID de um pagamento com falha.

Verificar se um pagamento pode ser repetido

GET /payments/{payment_id}/retry nunca falha para um pagamento inelegível. Em vez disso, ele retorna can_retry: false com o código reason, para que seu dashboard ou ferramenta de suporte possa mostrar o mesmo estado exibido pelo dashboard do Dodo Payments. Ele requer a função Viewer.

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
});

const state = await client.payments.retrieveRetryState('pay_0NmDtkE0iRvmeTcT6t0ol');

if (state.can_retry) {
  console.log(`Retry available. ${state.sends_used}/${state.sends_allowed} used.`);
} else {
  console.log(`Cannot retry: ${state.reason}. Next window: ${state.retry_available_at}`);
}

import os
from dodopayments import DodoPayments

client = DodoPayments(bearer_token=os.environ["DODO_PAYMENTS_API_KEY"])

state = client.payments.retrieve_retry_state("pay_0NmDtkE0iRvmeTcT6t0ol")

if state.can_retry:
    print(f"Retry available. {state.sends_used}/{state.sends_allowed} used.")
else:
    print(f"Cannot retry: {state.reason}. Next window: {state.retry_available_at}")

curl https://live.dodopayments.com/payments/pay_0NmDtkE0iRvmeTcT6t0ol/retry \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY"

Response

{
  "can_retry": false,
  "reason": "MANUAL_RETRY_LIMIT_REACHED",
  "sends_used": 1,
  "sends_allowed": 3,
  "retry_available_at": "2026-08-26T16:51:00Z"
}

Campo	Descrição
`can_retry`	`true` quando um retry seria enviado imediatamente.
`reason`	O código com o qual o retry falharia. `null` quando `can_retry` for `true`.
`sends_used`	Retries manuais já enviados para esta fatura.
`sends_allowed`	Sempre `3`.
`retry_available_at`	Quando o próximo retry manual será liberado. `null` quando não houver mais retries ou quando a recusa não estiver relacionada ao período de espera.

Enviar um retry manual

POST /payments/{payment_id}/retry cria um novo pagamento e cobra o método de pagamento salvo. Ele requer a função Editor.

const retry = await client.payments.retry('pay_0NmDtkE0iRvmeTcT6t0ol');

console.log(retry.payment_id, retry.status);

retry = client.payments.retry("pay_0NmDtkE0iRvmeTcT6t0ol")

print(retry.payment_id, retry.status)

curl -X POST https://live.dodopayments.com/payments/pay_0NmDtkE0iRvmeTcT6t0ol/retry \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY"

Response

{
  "payment_id": "pay_2IjeQm4hqU6RA4Z4kwDee",
  "invoice_id": "inv_9Kp2mQ7vRt4LxYw3",
  "status": "processing",
  "retry_attempt": 1,
  "is_manual_retry": true,
  "sends_used": 1,
  "sends_allowed": 3,
  "retry_available_at": "2026-08-26T16:51:00Z"
}

Campo	Descrição
`payment_id`	O novo pagamento criado para esta tentativa.
`invoice_id`	A fatura de renovação cobrada.
`status`	Resultado da cobrança. `processing` significa que o processador ainda não a liquidou. `null` significa que nenhum resultado foi registrado antes do retorno da resposta. Em ambos os casos, os webhooks de pagamento informam o resultado final.
`retry_attempt`	Posição desta tentativa entre os retries manuais da fatura, começando em `1`.
`is_manual_retry`	Sempre `true` neste endpoint.
`sends_used`, `sends_allowed`, `retry_available_at`	Estado do limite de retry após este envio. `retry_available_at` corresponde apenas ao relógio do período de espera. Ele é definido mesmo quando esta cobrança é bem-sucedida; nesse caso, a fatura é paga e nenhum retry adicional será liberado.

Respostas de erro

Status HTTP	Códigos	O que fazer
`404`	`NOT_FOUND`	O pagamento não pertence à sua empresa.
`409`	`MANUAL_RETRY_IN_FLIGHT`, `PREVIOUS_PAYMENT_PENDING`, `CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION`	Temporário ou algo precisa ser alterado primeiro. Aguarde o pagamento em andamento ou pendente chegar a um estado final, ou remova o cancelamento programado.
`422`	`PAYMENT_NOT_RETRYABLE`, `SUBSCRIPTION_INACTIVE`, `SUBSCRIPTION_HAS_NO_PAYMENT_METHOD`, `MANUAL_RETRY_HARD_DECLINE`, `MANUAL_RETRY_ALREADY_PAID`, `BYOP_CONNECTOR_DISABLED`, `MERCHANT_NOT_LIVE`	Este pagamento não pode ser repetido. Não repita a chamada.
`429`	`MANUAL_RETRY_LIMIT_REACHED`	Consulte o estado do retry e aguarde até `retry_available_at`, ou pare quando os três retries tiverem sido usados.

Cada código é descrito na referência de Códigos de erro.

Webhooks

Um retry manual cria um pagamento comum, portanto os mesmos webhooks são acionados como em qualquer tentativa de renovação:

Evento	É acionado quando
`payment.succeeded`	O retry foi cobrado. `subscription.active` ocorre em seguida, quando a assinatura é reativada.
`payment.failed`	O retry foi recusado. A assinatura permanece em `on_hold`, e nenhum retry automático é programado a partir de uma falha manual.
`payment.processing`	O processador aceitou a cobrança, mas ainda não a liquidou.

No objeto de pagamento desses eventos, retry_attempt é 1 ou superior e subscription_id é definido, exatamente como em um retry automático. Mantenha o payment_id da resposta do retry se precisar diferenciar uma tentativa manual de uma programada.

Payment Webhook Payloads

Esquemas completos de payload para eventos de pagamento.

Relacionados

Subscription Payment Retries

A programação automática de espera progressiva executada junto com os retries manuais.

Subscription Dunning

Envie um e-mail ao cliente para atualizar o método de pagamento após uma recusa definitiva.

Handle Payment Failures

Leia os códigos de recusa e decida quando vale a pena fazer um retry.

Error Codes

Cada código MANUAL_RETRY_*, seu acionador e sua mensagem.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

O que é o retry manual?

Repetir pelo dashboard

Elegibilidade

Limites de retry

Retries manuais vs. automáticos

Repetir pela API

Verificar se um pagamento pode ser repetido

Enviar um retry manual

Respostas de erro

Webhooks

Payment Webhook Payloads

Relacionados

Subscription Payment Retries

Subscription Dunning

Handle Payment Failures

Error Codes

​O que é o retry manual?

​Repetir pelo dashboard

​Elegibilidade

​Limites de retry

​Retries manuais vs. automáticos

​Repetir pela API

​Verificar se um pagamento pode ser repetido

​Enviar um retry manual

​Respostas de erro

​Webhooks

Payment Webhook Payloads

​Relacionados

Subscription Payment Retries

Subscription Dunning

Handle Payment Failures

Error Codes

O que é o retry manual?

Repetir pelo dashboard

Elegibilidade

Limites de retry

Retries manuais vs. automáticos

Repetir pela API

Verificar se um pagamento pode ser repetido

Enviar um retry manual

Respostas de erro

Webhooks

Relacionados