> ## 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.

> [!NOTE]
>
> 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](https://docs.dodopayments.com/features/recovery/payment-retries.md).

## O que é o retry manual?

Quando um pagamento de renovação falha, a assinatura passa para `on_hold`. Se você ativou [Payment Retries](https://docs.dodopayments.com/features/recovery/payment-retries.md), 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.

**1. Open the failed payment**

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

**2. 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](#eligibility).

**3. 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](https://mintcdn.com/dodopayments/0duTS18kYi2NwQ3m/images/recovery/manual-retry-transaction-details.png?fit=max\&auto=format\&n=0duTS18kYi2NwQ3m\&q=85\&s=5537fa5eff17cbe91a53599f887a26e7)

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](#retry-limits). | `MANUAL_RETRY_LIMIT_REACHED` |
| Cliente | O cliente não está na sua [blocklist](https://docs.dodopayments.com/features/customer-blocklist.md). | `PAYMENT_NOT_RETRYABLE` |
| Conector de pagamento | Para assinaturas [BYOP](https://docs.dodopayments.com/features/byop.md), o conector está ativado. | `BYOP_CONNECTOR_DISABLED` |
| Modo live | No modo live, sua empresa tem pagamentos live ativados. | `MERCHANT_NOT_LIVE` |

> [!NOTE]
>
> 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](https://docs.dodopayments.com/features/recovery/payment-retries.md#subscription-status-transitions).

> [!WARNING]
>
> 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](https://docs.dodopayments.com/features/recovery/subscription-dunning.md) 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](#check-whether-a-payment-can-be-retried) 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**.

```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 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.

```typescript Node.js theme={null}
// `client` is the DodoPayments instance from the previous example.
const retry = await client.payments.retry('pay_0NmDtkE0iRvmeTcT6t0ol');

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

```python Python theme={null}
# `client` is the DodoPayments instance from the previous example.
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 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](#check-whether-a-payment-can-be-retried) e aguarde até `retry_available_at`, ou pare quando as três tentativas tiverem sido usadas. |

A referência de [Error Codes](https://docs.dodopayments.com/api-reference/error-codes.md) 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.

> [card] [Payment Webhook Payloads](https://docs.dodopayments.com/developer-resources/webhooks/intents/payment.md)
>
> Esquemas completos de payload para eventos de pagamento.

## Relacionados

> [card] [Subscription Payment Retries](https://docs.dodopayments.com/features/recovery/payment-retries.md)
>
> A programação automática de back-off que é executada junto com as tentativas manuais.

> [card] [Subscription Dunning](https://docs.dodopayments.com/features/recovery/subscription-dunning.md)
>
> Envie um e-mail ao cliente para atualizar o método de pagamento após uma recusa definitiva.

> [card] [Handle Payment Failures](https://docs.dodopayments.com/developer-resources/handle-payment-failures.md)
>
> Leia os códigos de recusa e decida quando vale a pena tentar novamente.

> [card] [Error Codes](https://docs.dodopayments.com/api-reference/error-codes.md)
>
> Cada código `MANUAL_RETRY_*`, seu gatilho e sua mensagem.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.