> ## 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.
# Riprova manuale del pagamento
> Ripeti su richiesta il pagamento del rinnovo di un abbonamento non riuscito dalla dashboard o dall'API, invece di attendere il prossimo tentativo automatico.
Manual Retry ripete il pagamento del **rinnovo** di un abbonamento non riuscito nel momento in cui lo richiedi, dalla pagina dei dettagli del pagamento o tramite API. Addebita il metodo di pagamento salvato sull'abbonamento e viene eseguito indipendentemente dalla pianificazione di [Payment Retries](/features/recovery/payment-retries) automatici.
## Che cos'è Manual Retry?
Quando un pagamento di rinnovo non va a buon fine, l'abbonamento passa a `on_hold` e [Payment Retries](/features/recovery/payment-retries) ripete l'addebito secondo una pianificazione con intervalli crescenti. A volte sai che il pagamento andrà a buon fine subito: il cliente ha confermato di aver ricaricato il proprio conto oppure il tuo team di supporto è al telefono con lui. Manual Retry ti consente di inviare immediatamente un tentativo invece di attendere ore o giorni per quello pianificato successivo.
* **Solo pagamenti di rinnovo**: Manual Retry si applica alle fatture di rinnovo degli abbonamenti mentre l'abbonamento è `on_hold`. I pagamenti iniziali, i pagamenti una tantum, gli addebiti per il cambio di piano e gli addebiti su richiesta non sono idonei.
* **Nessuna azione da parte del cliente**: l'addebito viene effettuato sul metodo di pagamento già salvato sull'abbonamento.
* **Indipendente dalle riprove automatiche**: una riprova manuale non consuma un tentativo della pianificazione automatica, non sposta la prossima riprova pianificata e funziona anche quando Payment Retries è disattivato.
* **Ripete la fattura, non il pagamento**: un pagamento non riuscito è solo il punto di partenza. Dodo Payments individua la fattura di rinnovo aperta associata e addebita l'importo dovuto, quindi non importa da quale pagamento non riuscito della fattura avvii la riprova.
## Ripetere dal dashboard
Vai a **Transactions → Payments** e fai clic sul pagamento di rinnovo non riuscito per aprire la pagina **Transaction details**.
Fai clic su **Retry Payment Manually** nell'angolo in alto a destra. Il pulsante è disponibile solo mentre il pagamento è [idoneo](#eligibility).
Per il tentativo viene creato un nuovo pagamento, che compare nell'**Activity Log**. Se l'addebito va a buon fine, l'abbonamento torna a `active` e la data della fatturazione successiva avanza normalmente. Se il gestore dei pagamenti non ha ancora completato l'elaborazione dell'addebito, il pagamento risulta in corso finché il webhook `payment.succeeded` o `payment.failed` non comunica l'esito.
## Idoneità
Una riprova manuale viene inviata solo se tutti i controlli seguenti hanno esito positivo. La colonna **Reason code** indica ciò che restituisce l'API: in `reason` su `GET /payments/{payment_id}/retry` e come errore `code` su `POST /payments/{payment_id}/retry`.
| Controllo | Requisito | Codice motivo |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
| Tipo di pagamento | Un pagamento di **rinnovo** di un abbonamento la cui fattura è ancora aperta. I pagamenti senza fattura, i pagamenti iniziali, i pagamenti una tantum, gli addebiti per il cambio di piano e gli addebiti su richiesta non possono essere ripetuti. | `PAYMENT_NOT_RETRYABLE` |
| Stato dell'abbonamento | `on_hold` | `SUBSCRIPTION_INACTIVE` |
| Annullamento pianificato | L'abbonamento non è pianificato per l'annullamento alla prossima data di fatturazione. | `CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION` |
| Metodo di pagamento salvato | L'abbonamento dispone di un metodo di pagamento salvato da addebitare. | `SUBSCRIPTION_HAS_NO_PAYMENT_METHOD` |
| Ultimo errore | L'errore più recente è un **rifiuto temporaneo**. Un rifiuto definitivo o un errore senza codice classificato non può essere ripetuto. | `MANUAL_RETRY_HARD_DECLINE` |
| Nessuna operazione in corso | Nessun pagamento della fattura è `processing` o non ha ancora uno stato registrato. Si tratta di un tentativo, manuale o automatico, appena inviato e che non ha ancora restituito un risultato. Attendi prima il relativo esito. | `MANUAL_RETRY_IN_FLIGHT` |
| Ultimo pagamento non riuscito | Il pagamento più recente della fattura ha lo stato `failed`. Un pagamento più recente con qualsiasi altro stato diverso da `failed`, ad esempio `requires_customer_action`, `requires_payment_method` o `cancelled`, blocca la riprova anche quando non ci sono operazioni in corso. | `PREVIOUS_PAYMENT_PENDING` |
| Non già pagato | Nessun pagamento della fattura è andato a buon fine. | `MANUAL_RETRY_ALREADY_PAID` |
| Limite delle riprove | Sono state inviate meno di 3 riprove manuali sulla fattura e il periodo di attesa è trascorso. Consulta [Limiti delle riprove](#retry-limits). | `MANUAL_RETRY_LIMIT_REACHED` |
| Cliente | Il cliente non è presente nella tua [blocklist](/features/customer-blocklist). | `PAYMENT_NOT_RETRYABLE` |
| Connettore di pagamento | Per gli abbonamenti [BYOP](/features/byop), il connettore è abilitato. | `BYOP_CONNECTOR_DISABLED` |
| Modalità live | In modalità live, la tua attività ha abilitato i pagamenti live. | `MERCHANT_NOT_LIVE` |
Manual Retry è più restrittivo delle riprove automatiche in un caso: richiede che l'abbonamento sia `on_hold`. Le riprove automatiche continuano per altri stati non attivi; consulta [Transizioni dello stato dell'abbonamento](/features/recovery/payment-retries#subscription-status-transitions).
Ripetere un rifiuto definitivo sulla stessa carta non può andare a buon fine e i rifiuti ripetuti danneggiano il tuo tasso di autorizzazione. Quando il motivo è `MANUAL_RETRY_HARD_DECLINE`, chiedi al cliente di aggiornare il metodo di pagamento. [Subscription Dunning](/features/recovery/subscription-dunning) esegue questa operazione automaticamente.
## Limiti delle riprove
Ogni fattura di rinnovo consente **3** riprove manuali, con un periodo di attesa tra una e l'altra:
| Riprova manuale | Disponibilità |
| --------------- | -------------------------------- |
| 1 | Non appena il pagamento è idoneo |
| 2 | 1 ora dopo la prima |
| 3 | 3 ore dopo la seconda |
I limiti si applicano sia in modalità test sia in modalità live. Quando una riprova viene rifiutata per questo motivo, l'API restituisce `MANUAL_RETRY_LIMIT_REACHED` (HTTP `429`). Il corpo dell'errore contiene solo `code` e `message`. Per sapere quando sarà disponibile la prossima riprova, [controlla lo stato della riprova](#check-whether-a-payment-can-be-retried) e leggi `retry_available_at`. Il valore è `null` quando sono state utilizzate tutte e tre.
Le riprove automatiche non vengono conteggiate in questo limite e le riprove manuali non vengono conteggiate tra gli 8 tentativi della pianificazione automatica.
## Riprove manuali e automatiche
| | Manual Retry | Payment Retries |
| -------------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **Attivazione** | Tu, dalla dashboard o dall'API | Dodo Payments, secondo una pianificazione con intervalli crescenti |
| **Tempistica** | Immediatamente | 12 ore dopo l'errore, poi a intervalli progressivamente più lunghi |
| **Tentativi** | 3 per fattura, con un periodo di attesa di 1 ora e poi di 3 ore | Fino a 8 per fattura, durante la finestra di recupero |
| **Richiede Payment Retries abilitato** | No | Sì |
| **Effetto sull'altro** | Nessuno. Un errore manuale non pianifica né sposta un tentativo automatico. | Nessuno. La catena automatica continua indipendentemente dagli invii manuali. |
| **Analisi** | Conteggiate nelle metriche **Payment retries** nella scheda Recovery | Conteggiate nelle stesse metriche |
## Ripetere tramite API
Controlla prima l'idoneità, quindi invia la riprova. Entrambi gli endpoint richiedono l'ID di un pagamento non riuscito.
### Verificare se un pagamento può essere ripetuto
`GET /payments/{payment_id}/retry` non restituisce mai un errore per un pagamento non idoneo. Restituisce invece `can_retry: false` con il codice `reason`, così la dashboard o gli strumenti di supporto possono mostrare lo stesso stato visualizzato dalla dashboard di Dodo Payments. Richiede il ruolo **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 | Descrizione |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `can_retry` | `true` quando una riprova verrebbe inviata immediatamente. |
| `reason` | Il codice con cui la riprova non andrebbe a buon fine. `null` quando `can_retry` è `true`. |
| `sends_used` | Riprove manuali già inviate su questa fattura. |
| `sends_allowed` | Sempre `3`. |
| `retry_available_at` | Quando sarà disponibile la prossima riprova manuale. `null` quando non rimangono riprove o quando il rifiuto non è dovuto al periodo di attesa. |
### Inviare una riprova manuale
`POST /payments/{payment_id}/retry` crea un nuovo pagamento e addebita il metodo di pagamento salvato. Richiede il ruolo **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 | Descrizione |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment_id` | Il nuovo pagamento creato per questo tentativo. |
| `invoice_id` | La fattura di rinnovo addebitata. |
| `status` | Esito dell'addebito. `processing` indica che il gestore non lo ha ancora completato. `null` indica che non è stato registrato alcun esito prima della restituzione della risposta. In entrambi i casi, i webhook del pagamento comunicano il risultato finale. |
| `retry_attempt` | Posizione di questo tentativo tra le riprove manuali della fattura, a partire da `1`. |
| `is_manual_retry` | Sempre `true` su questo endpoint. |
| `sends_used`, `sends_allowed`, `retry_available_at` | Stato del limite delle riprove dopo questo invio. `retry_available_at` indica solo il periodo di attesa. Viene impostato anche quando l'addebito va a buon fine; in tal caso la fattura è pagata e non sarà disponibile nessun'altra riprova. |
### Risposte di errore
| Stato HTTP | Codici | Azione |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `404` | `NOT_FOUND` | Il pagamento non appartiene alla tua attività. |
| `409` | `MANUAL_RETRY_IN_FLIGHT`, `PREVIOUS_PAYMENT_PENDING`, `CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION` | Temporaneo oppure è necessario modificare prima qualcos'altro. Attendi che il pagamento in corso o in sospeso raggiunga uno stato finale oppure rimuovi l'annullamento pianificato. |
| `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` | Questo pagamento non può essere ripetuto. Non ripetere la chiamata. |
| `429` | `MANUAL_RETRY_LIMIT_REACHED` | [Controlla lo stato della riprova](#check-whether-a-payment-can-be-retried) e attendi fino a `retry_available_at` oppure interrompi l'operazione quando sono state utilizzate tutte e tre le riprove. |
Ogni codice è descritto nella documentazione di riferimento [Error Codes](/api-reference/error-codes).
## Webhook
Una riprova manuale crea un normale pagamento, quindi vengono attivati gli stessi webhook di qualsiasi tentativo di rinnovo:
| Evento | Si attiva quando |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `payment.succeeded` | La riprova è stata addebitata. Segue `subscription.active` quando l'abbonamento viene riattivato. |
| `payment.failed` | La riprova è stata rifiutata. L'abbonamento rimane `on_hold` e da un errore manuale non viene pianificata alcuna riprova automatica. |
| `payment.processing` | Il gestore ha accettato l'addebito ma non lo ha ancora completato. |
Nell'oggetto del pagamento di questi eventi, `retry_attempt` è `1` o superiore e `subscription_id` è impostato, esattamente come per una riprova automatica. Conserva `payment_id` della risposta della riprova se devi distinguere un tentativo manuale da uno pianificato.
Schemi completi del payload per gli eventi di pagamento.
## Correlati
La pianificazione automatica con intervalli crescenti che viene eseguita insieme alle riprove manuali.
Invia un'email al cliente chiedendogli di aggiornare il metodo di pagamento dopo un rifiuto definitivo.
Leggi i codici di rifiuto e stabilisci quando vale la pena effettuare una riprova.
Ogni codice `MANUAL_RETRY_*`, il relativo trigger e il messaggio.