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
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
Come funziona l’on-demand
- Crei un abbonamento con l’oggetto
on_demandper autorizzare un metodo di pagamento e, facoltativamente, addebitare una somma iniziale. - Successivamente, crei addebiti contro tale abbonamento con importi personalizzati usando l’endpoint dedicato agli addebiti.
- 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
- Node.js SDK
- Python SDK
- Go SDK
- cURL
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):Charge request body parameters
Charge request body parameters
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.
- Node.js SDK
- Python SDK
- Go SDK
- cURL
Success
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
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.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)
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 alleT + X daysper 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_CARDDO_NOT_HONORFRAUDULENTPICKUP_CARDAUTHENTICATION_FAILURELOST_CARD
Per un elenco completo dei motivi di rifiuto e per sapere se possono essere corretti dall’utente, consulta la documentazione
Transaction Failures.
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 daysalla stessa HH:MM). - Mantieni e consulta il timestamp dell’ultimo pagamento riuscito
Tper 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
activee continua a essere addebitabile tramitePOST /subscriptions/{id}/chargefino alla data di cancellazione pianificata. cancel_at_next_billing_dateviene impostato sutruenella subscription.- Viene emesso un webhook
subscription.cancelledquando 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}- Cancel immediately
- Cancel at next billing date
Imposta
status della subscription su cancelled per terminarla immediatamente. Il mandato viene revocato e non è possibile creare ulteriori addebiti.cURL
Webhook alla cancellazione
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
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_onlysia fornito durante la creazione e cheproduct_pricesia 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.