Skip to main content

Panoramica

Le sottoscrizioni on-demand ti consentono di autorizzare un metodo di pagamento di un cliente una sola volta e poi addebitare importi variabili ogni volta che ne hai bisogno, invece di seguire un programma fisso. Questa funzionalità è disponibile per tutti gli account—non è necessaria alcuna approvazione. Usa questa guida per:
  • Creare una sottoscrizione on-demand (autorizzare un mandato con un prezzo iniziale opzionale)
  • Attivare addebiti successivi con importi personalizzati
  • Monitorare i risultati utilizzando i webhook
Per una configurazione generale della sottoscrizione, consulta la Guida all’integrazione delle sottoscrizioni.

Requisiti

  • Account commerciante Dodo Payments e chiave API
  • Segreto del webhook configurato e un endpoint per ricevere eventi
  • Un prodotto in abbonamento nel tuo catalogo
This guide creates the on-demand subscription through a checkout session (POST /checkouts), which always returns a hosted checkout_url. Redirect the customer there to approve the mandate, and set return_url to where they should land afterward.

Come funziona l’on-demand

  1. Crei un abbonamento con l’oggetto on_demand per autorizzare un metodo di pagamento e, facoltativamente, addebitare una somma iniziale.
  2. Successivamente, crei addebiti contro tale abbonamento con importi personalizzati usando l’endpoint dedicato agli addebiti.
  3. Ascolti i webhook (es. payment.succeeded, payment.failed) per aggiornare il tuo sistema.

Crea una sottoscrizione on-demand

Endpoint: POST /checkouts Campi chiave della richiesta (corpo):
Trovali in Crea sessione di checkout

Crea una sottoscrizione on-demand

Success

Addebita una sottoscrizione on-demand

Dopo che il mandato è stato autorizzato, crea addebiti secondo necessità. Endpoint: POST /subscriptions/{subscription_id}/charge Campi chiave della richiesta (corpo):
integer
obbligatorio
Importo da addebitare (nell’unità monetaria più piccola). Esempio: per addebitare $25,00, passa 2500.
string
Sovrascrittura facoltativa della valuta per l’addebito.
string
Sovrascrittura facoltativa della descrizione per questo addebito.
boolean
Se true, include le commissioni in valuta adattiva all’interno di product_price. Se false, le commissioni vengono aggiunte sopra.
object
Specifica come utilizzare il saldo del wallet del cliente per saldare questo addebito.
object
Metadati aggiuntivi per il pagamento. Se omessi, vengono utilizzati i metadati della subscription.
Success
L’addebito di una subscription che non è on-demand potrebbe non riuscire. Assicurati che la subscription includa on_demand: true nei propri dettagli prima di effettuare l’addebito.

Gestire gli addebiti non riusciti

Quando un addebito su una subscription on-demand non riesce, decidi tu cosa succede dopo. A differenza delle subscription pianificate — per le quali un rinnovo non riuscito interrompe la fatturazione automatica successiva — le subscription on-demand restano addebitabili dopo un errore. Puoi chiamare nuovamente l’endpoint di addebito nell’ambito della tua logica di retry.

Cosa succede in caso di errore

1

Charge attempt fails

La richiesta POST /subscriptions/{subscription_id}/charge restituisce una risposta di errore oppure viene completata in modo asincrono ed emette un webhook payment.failed con il motivo del rifiuto.
2

Subscription may transition to on_hold

La subscription potrebbe passare allo stato on_hold ed emettere un webhook subscription.on_hold (vedi Stati della subscription → On Hold). Si tratta di un segnale, non di un blocco. Per le subscription on-demand, on_hold non impedisce di effettuare nuovamente un addebito.
3

Retry the charge (your call)

Per i flussi on-demand, Dodo non effettua retry automatici. Puoi chiamare nuovamente POST /subscriptions/{subscription_id}/charge in qualsiasi momento per riprovare. Applica la policy di retry sicuro riportata di seguito — utilizza un backoff esponenziale, ignora i rifiuti definitivi ed evita i pattern di richieste ravvicinate — in modo che i retry non vengano segnalati dai nostri sistemi antifrode e di gestione del rischio.
4

Optionally, ask the customer for a new payment method

Se i retry continuano a non riuscire perché il metodo di pagamento presenta un problema (carta scaduta, conto chiuso e così via), utilizza POST /subscriptions/{subscription_id}/update-payment-method per raccoglierne uno nuovo dal cliente. In caso di successo, la subscription torna a active e vengono emessi webhook payment.succeeded e successivamente subscription.active.
On-demand vs pianificate: per le subscription pianificate, Dodo gestisce i propri retry del rinnovo e il dunning. Per le subscription on-demand, la policy di retry è sotto la tua responsabilità, perché solo tu sai quando deve avvenire il prossimo addebito (dipende dai tuoi eventi di utilizzo, non da un calendario).

Sequenza dei webhook per un addebito on-demand non riuscito

Gli eventi 3 e 4 vengono attivati solo dopo il successo di un addebito successivo.

Responsabilità dei retry

Dodo Payments non effettua retry automatici degli addebiti on-demand non riusciti. La policy di retry è sotto la tua responsabilità. Segui le linee guida per retry sicuri riportate di seguito per evitare che i nostri sistemi di rilevamento delle frodi ti segnalino come attività di card testing.
Dunning delle subscription — la sequenza integrata di email per il recupero — riguarda i pagamenti di rinnovo non riusciti delle subscription pianificate e le cancellazioni avviate dal cliente. Non è progettata per gli addebiti on-demand non riusciti. Quando ritieni necessario aggiornare il metodo di pagamento, comunica direttamente con il cliente (ad esempio tramite un’email transazionale o una richiesta nell’app).

Retry dei pagamenti

Il nostro sistema di rilevamento delle frodi potrebbe bloccare pattern di retry aggressivi (e segnalarli come potenziale card testing). Segui una policy di retry sicura.
I pattern di retry ravvicinati possono essere segnalati come fraudolenti o come sospetto card testing dai nostri sistemi di gestione del rischio e dai processor. Evita retry raggruppati; segui la pianificazione del backoff e le indicazioni sull’allineamento temporale riportate di seguito.

Principi per policy di retry sicure

  • Meccanismo di backoff: utilizza un backoff esponenziale tra i retry.
  • Limiti dei retry: limita il numero totale di retry (massimo 3–4 tentativi).
  • Filtraggio intelligente: effettua retry solo per gli errori che possono essere risolti con un retry (ad esempio errori di rete o dell’issuer, fondi insufficienti); non effettuare mai retry per i rifiuti definitivi.
  • Prevenzione del card testing: non effettuare retry per errori come DO_NOT_HONOR, STOLEN_CARD, LOST_CARD, PICKUP_CARD, FRAUDULENT, AUTHENTICATION_FAILURE.
  • Variazione dei metadati (facoltativa): se gestisci un tuo sistema di retry, differenzia i retry tramite i metadati (ad esempio retry_attempt).

Pianificazione dei retry consigliata (subscription)

  • 1° tentativo: immediatamente, quando crei l’addebito
  • 2° tentativo: dopo 3 giorni
  • 3° tentativo: dopo altri 7 giorni (10 giorni totali)
  • 4° tentativo (finale): dopo altri 7 giorni (17 giorni totali)
Passaggio finale: se il pagamento non è ancora stato effettuato, contrassegna la subscription come non pagata o cancellala, in base alla tua policy. Avvisa il cliente durante l’intervallo disponibile affinché aggiorni il metodo di pagamento.

Evita retry ravvicinati; allineali all’orario dell’autorizzazione

  • Ancora i retry al timestamp dell’autorizzazione originale per evitare comportamenti “ravvicinati” nell’intero portafoglio.
  • Esempio: se il cliente avvia un periodo di prova o un mandato oggi alle 13:10, pianifica i retry successivi alle 13:10 dei giorni seguenti in base al tuo backoff (ad esempio +3 giorni → 13:10, +7 giorni → 13:10).
  • In alternativa, se memorizzi l’orario dell’ultimo pagamento riuscito T, pianifica il tentativo successivo alle T + X days per mantenere l’allineamento dell’orario.
Fuso orario e DST: utilizza uno standard temporale coerente per la pianificazione e converti l’orario solo per la visualizzazione, così da mantenere gli intervalli.

Codici di rifiuto per i quali non dovresti effettuare retry

  • STOLEN_CARD
  • DO_NOT_HONOR
  • FRAUDULENT
  • PICKUP_CARD
  • AUTHENTICATION_FAILURE
  • LOST_CARD
Per un elenco completo dei motivi di rifiuto e per sapere se possono essere corretti dall’utente, consulta la documentazione Transaction Failures.
Effettua retry solo per problemi temporanei o risolvibili (ad esempio insufficient_funds, issuer_unavailable, processing_error e timeout di rete). Se lo stesso rifiuto si ripete, interrompi i retry successivi.

Linee guida di implementazione (senza codice)

  • Utilizza uno scheduler o una coda che mantenga timestamp precisi; calcola il tentativo successivo all’orario esatto dell’offset (ad esempio T + 3 days alla stessa HH:MM).
  • Mantieni e consulta il timestamp dell’ultimo pagamento riuscito T per calcolare il tentativo successivo; non raggruppare più subscription nello stesso istante.
  • Valuta sempre l’ultimo motivo del rifiuto; interrompi i retry per i rifiuti definitivi presenti nell’elenco da ignorare riportato sopra.
  • Limita i retry simultanei per cliente e per account per evitare picchi accidentali.
  • Comunica in modo proattivo: invia un’email o un SMS al cliente chiedendogli di aggiornare il metodo di pagamento prima del tentativo pianificato successivo.
  • Utilizza i metadati solo per l’osservabilità (ad esempio retry_attempt); non cercare mai di “eludere” i sistemi antifrode o di gestione del rischio ruotando campi irrilevanti.

Cancellazione

Le subscription on-demand seguono un flusso di cancellazione diverso da quello delle subscription pianificate, perché non esiste un ciclo di fatturazione fisso a cui ancorare una data di fine immediata.

Comportamento del customer portal

Quando un cliente cancella una subscription on-demand dal Customer Portal, la cancellazione viene pianificata per la data di fatturazione successiva per impostazione predefinita. L’opzione Cancella ora non viene mostrata intenzionalmente per le subscription on-demand. Il motivo è il seguente: le subscription on-demand non hanno date di rinnovo ricorrenti prevedibili; l’orario del prossimo addebito dipende interamente dai tuoi eventi di utilizzo. Pianificare la cancellazione alla data di fatturazione successiva mantiene attivo il mandato fino alla fine del periodo, consentendo di addebitare l’eventuale utilizzo in corso e terminando poi la subscription correttamente. Dopo che il cliente conferma la cancellazione:
  • La subscription resta active e continua a essere addebitabile tramite POST /subscriptions/{id}/charge fino alla data di cancellazione pianificata.
  • cancel_at_next_billing_date viene impostato su true nella subscription.
  • Viene emesso un webhook subscription.cancelled quando la cancellazione diventa effettiva.
Se devi terminare immediatamente la subscription (ad esempio in risposta a un rimborso o a una richiesta di assistenza), cancellala programmaticamente tramite l’API invece di affidarti al flusso del customer portal.

Cancellare programmaticamente

Puoi cancellare una subscription on-demand tramite l’API in qualsiasi momento. Sei tu a controllare se la cancellazione è immediata o pianificata. Endpoint: PATCH /subscriptions/{subscription_id}
Imposta status della subscription su cancelled per terminarla immediatamente. Il mandato viene revocato e non è possibile creare ulteriori addebiti.
cURL

Webhook alla cancellazione

Per distinguere le cancellazioni on-demand da quelle delle subscription pianificate nel tuo handler, controlla il flag on_demand della subscription durante l’elaborazione del webhook.

Monitorare gli esiti con i webhook

Implementa la gestione dei webhook per monitorare il percorso del cliente. Vedi Implementazione dei webhook.
  • subscription.active: mandato autorizzato e subscription attivata
  • subscription.failed: creazione non riuscita (ad esempio, errore del mandato)
  • subscription.on_hold: subscription messa in sospeso (ad esempio, stato non pagato)
  • subscription.cancelled: subscription completamente cancellata (vedi Cancellazione)
  • payment.succeeded: addebito riuscito
  • payment.failed: addebito non riuscito
Per i flussi on-demand, concentrati su payment.succeeded e payment.failed per riconciliare gli addebiti basati sull’utilizzo. Quando payment.failed è seguito da subscription.on_hold, consulta Gestire gli addebiti non riusciti per recuperare la subscription.

Test e passaggi successivi

1

Create in test mode

Utilizza la tua API key di test per creare la subscription, quindi apri checkout_url restituito e completa il mandato.
2

Trigger a charge

Chiama l’endpoint di addebito con un product_price ridotto (ad esempio 100) e verifica di ricevere payment.succeeded.
3

Go live

Passa alla tua API key live dopo aver convalidato gli eventi e gli aggiornamenti dello stato interno.

Risoluzione dei problemi

  • 422 Invalid Request: assicurati che on_demand.mandate_only sia fornito durante la creazione e che product_price sia fornito per gli addebiti.
  • Errori di valuta: se sostituisci product_currency, verifica che sia supportato per il tuo account e il tuo cliente.
  • Nessun webhook ricevuto: verifica la configurazione dell’URL del webhook e del secret della firma.
Ultima modifica il 6 agosto 2026