Riprova manuale del pagamento

Manual Retry ritenta il pagamento di rinnovo di un abbonamento non riuscito quando lo richiedi, dalla pagina dei dettagli del pagamento o tramite API. Addebita il metodo di pagamento salvato sull’abbonamento e opera indipendentemente dalla pianificazione automatica di Payment Retries.

Che cos’è Manual Retry?

Quando un pagamento di rinnovo non va a buon fine, l’abbonamento passa a on_hold. Se hai attivato Payment Retries, il sistema ritenta l’addebito secondo una pianificazione con back-off. 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 invia immediatamente un tentativo, invece di aspettare 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 cambio piano e gli addebiti on-demand non sono idonei.
Nessuna azione del cliente: l’addebito viene effettuato sul metodo di pagamento già salvato sull’abbonamento.
Indipendente dai retry automatici: un retry manuale non consuma un tentativo della pianificazione automatica, non sposta il prossimo retry pianificato e funziona anche quando Payment Retries è disattivato.
Ritenta la fattura, non il pagamento: il pagamento non riuscito è solo il punto di ingresso. 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 il retry.

Ripetere dal dashboard

Solo gli utenti con il ruolo Owner o Editor possono inviare un retry manuale.

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

Dodo Payments crea un nuovo pagamento per il tentativo, che compare nell’Activity Log. Se l’addebito va a buon fine, l’abbonamento torna a active e la data di fatturazione successiva viene spostata a un periodo di fatturazione dopo il retry riuscito. Se il processore di pagamento non ha ancora regolato l’addebito, il pagamento viene mostrato come 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à

Dodo Payments invia un retry manuale solo quando tutti i controlli della tabella vengono superati. 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 cambio piano e gli addebiti on-demand non possono essere ritentati.	`PAYMENT_NOT_RETRYABLE`
Stato dell’abbonamento	`on_hold`	`SUBSCRIPTION_INACTIVE`
Annullamento pianificato	L’abbonamento non è pianificato per essere annullato 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 soft decline. Un hard decline o un errore senza codice classificato non può essere ritentato.	`MANUAL_RETRY_HARD_DECLINE`
Nessuna operazione in corso	Nessun pagamento della fattura è `processing` o è ancora privo di uno stato registrato. Tale pagamento è un tentativo, manuale o automatico, appena inviato e di cui non è ancora stato comunicato l’esito. Attendi prima il relativo esito.	`MANUAL_RETRY_IN_FLIGHT`
Il pagamento più recente non è riuscito	Il pagamento più recente della fattura ha lo stato `failed`. Qualsiasi altro stato, come `requires_customer_action`, `requires_payment_method` o `cancelled`, blocca il retry anche quando non ci sono operazioni in corso.	`PREVIOUS_PAYMENT_PENDING`
Non già pagata	Nessun pagamento della fattura è andato a buon fine.	`MANUAL_RETRY_ALREADY_PAID`
Limite dei retry	Sono stati inviati meno di 3 retry manuali sulla fattura e il periodo di attesa è trascorso. Consulta Retry Limits.	`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 dei retry automatici in un aspetto: richiede che l’abbonamento sia on_hold. Un abbonamento past_due in un periodo di tolleranza non supera questo controllo. I retry automatici continuano a essere eseguiti per altri stati non attivi. Consulta Subscription Status Transitions.

Ritentare un hard decline 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 dei retry

Ogni fattura di rinnovo consente 3 retry manuali, con un periodo di attesa tra l’uno e l’altro:

Retry manuale	Disponibilità
1	Non appena il pagamento è idoneo
2	1 ora dopo il primo
3	3 ore dopo il secondo

I limiti si applicano sia in modalità test sia in modalità live. Quando il limite impedisce un retry, l’API restituisce MANUAL_RETRY_LIMIT_REACHED (HTTP 429) e il corpo dell’errore contiene solo code e message. Per sapere quando sarà disponibile il retry successivo, controlla lo stato del retry e leggi retry_available_at. Il valore è null una volta utilizzati tutti e tre i retry. I retry automatici non vengono conteggiati in questo limite e i retry manuali non vengono conteggiati negli 8 tentativi della pianificazione automatica.

Retry manuali e automatici

I due percorsi di retry differiscono nei seguenti aspetti:

	Manual Retry	Payment Retries
Attivazione	Tu, dalla dashboard o dall’API	Dodo Payments, secondo una pianificazione con back-off
Tempistica	Immediatamente	12 ore dopo l’errore, quindi 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, all’interno della 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.
Analytics	Conteggiati nelle metriche Payment Retries in Analytics → Recovery	Conteggiati nelle stesse metriche

Retry tramite API

Controlla prima l’idoneità, quindi invia il retry. Entrambi gli endpoint accettano l’ID di un pagamento non riuscito.

Verificare se un pagamento può essere ritentato

GET /payments/{payment_id}/retry non restituisce un errore per un pagamento non idoneo. Restituisce invece can_retry: false con il codice reason, così la tua dashboard o i tuoi strumenti di supporto possono mostrare lo stesso stato della 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 un retry verrebbe inviato immediatamente.
`reason`	Il codice con cui il retry non riuscirebbe. `null` quando `can_retry` è `true`.
`sends_used`	Numero di retry manuali già inviati sulla fattura.
`sends_allowed`	Sempre `3` su questo endpoint.
`retry_available_at`	Quando sarà disponibile il prossimo retry manuale. `null` quando non rimangono retry o quando il rifiuto non è correlato al periodo di attesa.

Inviare un retry manuale

POST /payments/{payment_id}/retry crea un nuovo pagamento e addebita il metodo di pagamento salvato. Richiede il ruolo Editor. Gli esempi SDK riutilizzano client dell’esempio precedente.

// `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	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 processore non lo ha ancora regolato. `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 i retry 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 dei retry dopo questo invio. `retry_available_at` indica solo il timer del periodo di attesa. Viene impostato anche quando l’addebito va a buon fine; in tal caso la fattura è pagata e non sarà disponibile alcun altro retry.

Risposte di errore

Quando un retry non è consentito, POST restituisce uno dei seguenti HTTP status:

HTTP status	Codici	Cosa fare
`404`	`NOT_FOUND`	Il pagamento non appartiene alla tua attività.
`409`	`MANUAL_RETRY_IN_FLIGHT`, `PREVIOUS_PAYMENT_PENDING`, `CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION`	Il blocco è 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 ritentato. Non ripetere la chiamata.
`429`	`MANUAL_RETRY_LIMIT_REACHED`	Controlla lo stato del retry e attendi fino a `retry_available_at` oppure interrompi i tentativi una volta utilizzati tutti e tre.

La documentazione di riferimento degli Error Codes descrive ogni codice.

Webhook

Un retry manuale crea un pagamento ordinario, quindi vengono attivati gli stessi webhook di qualsiasi tentativo di rinnovo:

Evento	Si attiva quando
`payment.succeeded`	Il retry è stato addebitato. `subscription.active` segue quando l’abbonamento viene riattivato.
`payment.failed`	Il retry è stato rifiutato. L’abbonamento rimane `on_hold` e un errore manuale non pianifica un retry automatico.
`payment.processing`	Il processore ha accettato l’addebito ma non lo ha ancora regolato.

Nell’oggetto pagamento di questi eventi, retry_attempt è 1 o superiore e subscription_id è impostato, come per un retry automatico. L’oggetto pagamento non dispone di un campo che contrassegni un tentativo manuale, quindi conserva payment_id della risposta del retry 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 back-off che viene eseguita insieme ai retry manuali.

Subscription Dunning

Invia un’email al cliente per aggiornare il metodo di pagamento dopo un hard decline.

Handle Payment Failures

Leggi i codici di rifiuto e decidi quando vale la pena effettuare un retry.

Error Codes

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

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Che cos’è Manual Retry?

Ripetere dal dashboard

Idoneità

Limiti dei retry

Retry manuali e automatici

Retry tramite API

Verificare se un pagamento può essere ritentato

Inviare un retry 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 dei retry

​Retry manuali e automatici

​Retry tramite API

​Verificare se un pagamento può essere ritentato

​Inviare un retry 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 dei retry

Retry manuali e automatici

Retry tramite API

Verificare se un pagamento può essere ritentato

Inviare un retry manuale

Risposte di errore

Webhook

Correlati