> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Retry manual de pagamento
> Repita sob demanda um pagamento de renovação de assinatura com falha pelo dashboard ou pela API, em vez de aguardar o próximo retry automático.
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](/features/recovery/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](/features/recovery/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
Acesse **Transactions → Payments** e clique no pagamento de renovação com falha para abrir a página **Transaction details**.
Clique em **Retry Payment Manually** no canto superior direito. O botão fica disponível somente enquanto o pagamento estiver [elegível](#eligibility).
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.
## 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](#retry-limits). | `MANUAL_RETRY_LIMIT_REACHED` |
| Cliente | O cliente não está na sua [blocklist](/features/customer-blocklist). | `PAYMENT_NOT_RETRYABLE` |
| Conector de pagamento | Para assinaturas [BYOP](/features/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](/features/recovery/payment-retries#subscription-status-transitions).
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](/features/recovery/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](#check-whether-a-payment-can-be-retried) 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**.
```typescript Node.js theme={null}
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}`);
}
```
```python Python theme={null}
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}")
```
```bash cURL theme={null}
curl https://live.dodopayments.com/payments/pay_0NmDtkE0iRvmeTcT6t0ol/retry \
-H "Authorization: Bearer $DODO_PAYMENTS_API_KEY"
```
```json Response theme={null}
{
"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**.
```typescript Node.js theme={null}
const retry = await client.payments.retry('pay_0NmDtkE0iRvmeTcT6t0ol');
console.log(retry.payment_id, retry.status);
```
```python Python theme={null}
retry = client.payments.retry("pay_0NmDtkE0iRvmeTcT6t0ol")
print(retry.payment_id, retry.status)
```
```bash cURL theme={null}
curl -X POST https://live.dodopayments.com/payments/pay_0NmDtkE0iRvmeTcT6t0ol/retry \
-H "Authorization: Bearer $DODO_PAYMENTS_API_KEY"
```
```json Response theme={null}
{
"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](#check-whether-a-payment-can-be-retried) 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](/api-reference/error-codes).
## 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.
Esquemas completos de payload para eventos de pagamento.
## Relacionados
A programação automática de espera progressiva executada junto com os retries manuais.
Envie um e-mail ao cliente para atualizar o método de pagamento após uma recusa definitiva.
Leia os códigos de recusa e decida quando vale a pena fazer um retry.
Cada código `MANUAL_RETRY_*`, seu acionador e sua mensagem.