Riprova manuale del pagamento

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

Che cos’è Manual Retry?

Quando un pagamento di rinnovo non va a buon fine, l’abbonamento passa a on_hold e 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

Open the failed payment

Vai a Transactions → Payments e fai clic sul pagamento di rinnovo non riuscito per aprire la pagina Transaction details.

Click Retry Payment Manually

Fai clic su Retry Payment Manually nell’angolo in alto a destra. Il pulsante è disponibile solo mentre il pagamento è idoneo.

Check the result

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.

Pagina dei dettagli della transazione per un pagamento non riuscito che mostra il codice e il messaggio di errore, un Activity Log e un pulsante Retry Payment Manually — Retry Payment Manually on the transaction details page of a failed renewal

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.	`MANUAL_RETRY_LIMIT_REACHED`
Cliente	Il cliente non è presente nella tua blocklist.	`PAYMENT_NOT_RETRYABLE`
Connettore di pagamento	Per gli abbonamenti 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.

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

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

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

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.

Payment Webhook Payloads

Schemi completi del payload per gli eventi di pagamento.

Correlati

Subscription Payment Retries

La pianificazione automatica con intervalli crescenti che viene eseguita insieme alle riprove manuali.

Subscription Dunning

Invia un’email al cliente chiedendogli di aggiornare il metodo di pagamento dopo un rifiuto definitivo.

Handle Payment Failures

Leggi i codici di rifiuto e stabilisci quando vale la pena effettuare una riprova.

Error Codes

Ogni codice MANUAL_RETRY_*, il relativo trigger e il messaggio.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Che cos’è Manual Retry?

Ripetere dal dashboard

Idoneità

Limiti delle riprove

Riprove manuali e automatiche

Ripetere tramite API

Verificare se un pagamento può essere ripetuto

Inviare una riprova manuale

Risposte di errore

Webhook

Payment Webhook Payloads

Correlati

Subscription Payment Retries

Subscription Dunning

Handle Payment Failures

Error Codes

​Che cos’è Manual Retry?

​Ripetere dal dashboard

​Idoneità

​Limiti delle riprove

​Riprove manuali e automatiche

​Ripetere tramite API

​Verificare se un pagamento può essere ripetuto

​Inviare una riprova manuale

​Risposte di errore

​Webhook

Payment Webhook Payloads

​Correlati

Subscription Payment Retries

Subscription Dunning

Handle Payment Failures

Error Codes

Che cos’è Manual Retry?

Ripetere dal dashboard

Idoneità

Limiti delle riprove

Riprove manuali e automatiche

Ripetere tramite API

Verificare se un pagamento può essere ripetuto

Inviare una riprova manuale

Risposte di errore

Webhook

Correlati