Retry manual de pagamento

Manual Retry tenta novamente um pagamento de renovação de assinatura que falhou quando você solicita, na página de detalhes do pagamento ou por meio da API. Ele cobra o método de pagamento salvo na assinatura e é executado independentemente da programação automática de Payment Retries.

O que é o retry manual?

Quando um pagamento de renovação falha, a assinatura passa para on_hold. Se você ativou Payment Retries, o sistema tenta cobrar novamente conforme uma programação de back-off. À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 chamada com ele. Manual Retry envia uma tentativa imediatamente, em vez de esperar horas ou dias pela próxima tentativa programada.

Somente pagamentos de renovação: Manual Retry se aplica a faturas de renovação de assinaturas enquanto a assinatura está 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 das tentativas automáticas: uma tentativa manual não consome uma tentativa da programação automática, não altera a próxima tentativa programada e funciona mesmo quando Payment Retries está desativado.
Tenta novamente a fatura, não o pagamento: o pagamento com falha é apenas o ponto de entrada. Dodo Payments encontra a fatura de renovação em aberto associada a ele e cobra essa dívida; portanto, não importa a partir de qual pagamento com falha da fatura você inicia a nova tentativa.

Repetir pelo dashboard

Somente usuários com a função Owner ou Editor podem enviar uma tentativa manual.

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 está elegível.

Check the result

Dodo Payments cria um novo pagamento para a tentativa, que aparece no Activity Log. Se a cobrança for bem-sucedida, a assinatura retorna para active, e a próxima data de cobrança passa para um período de cobrança após a tentativa bem-sucedida. Se o processador de pagamentos ainda não tiver liquidado a cobrança, o pagamento aparecerá 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

Dodo Payments envia uma tentativa manual somente quando todas as verificações desta tabela 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	Reason code
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 tentados novamente.	`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 temporária. Uma recusa definitiva ou uma falha sem código de erro classificado não pode ser tentada novamente.	`MANUAL_RETRY_HARD_DECLINE`
Nenhum pagamento em andamento	Nenhum pagamento da fatura está em `processing` ou ainda sem um status registrado. Esse pagamento é uma tentativa, manual ou automática, que acabou de ser enviada e ainda não retornou um resultado. Aguarde o resultado primeiro.	`MANUAL_RETRY_IN_FLIGHT`
Pagamento mais recente com falha	O pagamento mais recente da fatura tem status `failed`. Qualquer outro status, como `requires_customer_action`, `requires_payment_method` ou `cancelled`, impede a nova tentativa mesmo quando não há nenhum pagamento em andamento.	`PREVIOUS_PAYMENT_PENDING`
Ainda não pago	Nenhum pagamento da fatura foi bem-sucedido.	`MANUAL_RETRY_ALREADY_PAID`
Limite de tentativas	Menos de 3 tentativas manuais foram enviadas para a fatura e o período de espera terminou. Consulte Retry Limits.	`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á ativado.	`BYOP_CONNECTOR_DISABLED`
Modo live	No modo live, sua empresa tem pagamentos live ativados.	`MERCHANT_NOT_LIVE`

Manual Retry é mais restrito do que as tentativas automáticas em um aspecto: exige que a assinatura esteja em on_hold. Uma assinatura past_due em um período de carência não passa nessa verificação. As tentativas automáticas continuam sendo executadas para outros status não ativos. Consulte Subscription Status Transitions.

Tentar novamente uma recusa definitiva no mesmo cartão não pode funcionar 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. Subscription Dunning faz isso automaticamente.

Limites de tentativas

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

Tentativa manual	Disponibilidade
1	Assim que o pagamento estiver elegível
2	1 hora após a primeira
3	3 horas após a segunda

Os limites se aplicam tanto ao modo de teste quanto ao modo live. Quando o limite recusa uma tentativa, a API retorna MANUAL_RETRY_LIMIT_REACHED (HTTP 429), e o corpo do erro contém somente code e message. Para saber quando a próxima tentativa será liberada, consulte o estado da tentativa e leia retry_available_at. Ele é null quando as três tentativas já tiverem sido usadas. As tentativas automáticas não contam para esse limite, e as tentativas manuais não contam para as 8 tentativas da programação automática.

Tentativas manuais e automáticas

Os dois caminhos de tentativa diferem das seguintes formas:

	Manual Retry	Payment Retries
Gatilho	Você, pelo dashboard ou pela API	Dodo Payments, conforme uma programação de back-off
Momento	Imediatamente	12 horas após a falha e, depois, em intervalos progressivamente maiores
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 ativado	Não	Sim
Efeito sobre o outro	Nenhum. Uma falha manual não agenda nem altera uma tentativa automática.	Nenhum. A sequência automática continua independentemente das tentativas manuais.
Analytics	Contabilizada nas métricas de Payment Retries em Analytics → Recovery	Contabilizada nas mesmas métricas

Tentativa novamente por meio da API

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

Verificar se um pagamento pode ser tentado novamente

GET /payments/{payment_id}/retry não retorna um erro para um pagamento inelegível. Em vez disso, retorna can_retry: false com o código reason, para que seu próprio dashboard ou ferramenta de suporte possa mostrar o mesmo estado do dashboard da Dodo Payments. Essa operação exige 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 uma tentativa seria enviada neste momento.
`reason`	O código com o qual a tentativa falharia. `null` quando `can_retry` for `true`.
`sends_used`	Tentativas manuais já enviadas para esta fatura.
`sends_allowed`	Sempre `3` neste endpoint.
`retry_available_at`	Quando a próxima tentativa manual será liberada. `null` quando não houver mais tentativas ou quando a recusa não estiver relacionada ao período de espera.

Enviar uma tentativa manual

POST /payments/{payment_id}/retry cria um novo pagamento e cobra o método de pagamento salvo. Essa operação exige a função Editor. Os exemplos do SDK reutilizam client do exemplo anterior.

// `client` is the DodoPayments instance from the previous example.
const retry = await client.payments.retry('pay_0NmDtkE0iRvmeTcT6t0ol');

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

# `client` is the DodoPayments instance from the previous example.
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 as tentativas 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 tentativas após este envio. `retry_available_at` corresponde apenas ao relógio do período de espera. Ele é definido mesmo quando a cobrança é bem-sucedida; nesse caso, a fatura é paga e nenhuma nova tentativa será liberada.

Respostas de erro

Quando uma tentativa não é permitida, POST retorna um dos seguintes status HTTP:

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`	O bloqueio é temporário ou algo mais precisa ser alterado primeiro. Aguarde até que o pagamento em andamento ou pendente alcance 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`	Não é possível tentar novamente este pagamento. Não repita a chamada.
`429`	`MANUAL_RETRY_LIMIT_REACHED`	Consulte o estado da tentativa e aguarde até `retry_available_at`, ou pare quando as três tentativas tiverem sido usadas.

A referência de Error Codes descreve todos os códigos.

Webhooks

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

Evento	Disparado quando
`payment.succeeded`	A tentativa foi cobrada. `subscription.active` é disparado em seguida, quando a assinatura é reativada.
`payment.failed`	A tentativa foi recusada. A assinatura permanece em `on_hold`, e uma falha manual não agenda uma tentativa automática.
`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 está definido, da mesma forma que em uma tentativa automática. O objeto de pagamento não tem um campo que identifique uma tentativa manual; portanto, mantenha payment_id da resposta da tentativa se precisar distinguir 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 back-off que é executada junto com as tentativas 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 tentar novamente.

Error Codes

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

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

O que é o retry manual?

Repetir pelo dashboard

Elegibilidade

Limites de tentativas

Tentativas manuais e automáticas

Tentativa novamente por meio da API

Verificar se um pagamento pode ser tentado novamente

Enviar uma tentativa 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 tentativas

​Tentativas manuais e automáticas

​Tentativa novamente por meio da API

​Verificar se um pagamento pode ser tentado novamente

​Enviar uma tentativa 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 tentativas

Tentativas manuais e automáticas

Tentativa novamente por meio da API

Verificar se um pagamento pode ser tentado novamente

Enviar uma tentativa manual

Respostas de erro

Webhooks

Relacionados