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
Importo da addebitare (nell’unità monetaria più piccola). Esempio: per addebitare $25,00, passa
2500.Sovrascrittura facoltativa della valuta per l’addebito.
Sovrascrittura facoltativa della descrizione per questo addebito.
Se true, include le commissioni in valuta adattiva all’interno di
product_price. Se false, le commissioni vengono aggiunte sopra.Metadata aggiuntivi per il pagamento. Se omessi, vengono usati i metadata dell’abbonamento.
- Node.js SDK
- Python SDK
- Go SDK
- cURL
Success
Riprova ai pagamenti
Il nostro sistema di rilevamento delle frodi potrebbe bloccare schemi di ripetizione aggressivi (e può contrassegnarli come potenziale test di carte). Segui una politica di ripetizione sicura.Principi per politiche di ripetizione sicure
- Meccanismo di backoff: Usa il backoff esponenziale tra i retry.
- Limiti di retry: Limita i retry totali (max 3–4 tentativi).
- Filtraggio intelligente: Riprova solo su errori ripetibili (es. errori di rete/issuer, fondi insufficienti); non riprovare mai rifiuti hard.
- Prevenzione dei test di carte: Non riprovare errori come
DO_NOT_HONOR,STOLEN_CARD,LOST_CARD,PICKUP_CARD,FRAUDULENT,AUTHENTICATION_FAILURE. - Varia i metadata (opzionale): Se gestisci il tuo sistema di retry, differenzia i retry tramite metadata (es.
retry_attempt).
Programma di ripetizione suggerito (sottoscrizioni)
- 1° tentativo: Immediato 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 ripetizioni a raffica; allineati all’orario di autorizzazione
- Ancorare i retry al timestamp originale dell’autorizzazione per evitare comportamenti a «raffica» nel tuo portfolio.
- Esempio: se il cliente avvia una prova o un mandato alle 13:10 di oggi, pianifica i retry successivi alle 13:10 dei giorni successivi secondo il tuo backoff (es. +3 giorni → 13:10, +7 giorni → 13:10).
- In alternativa, se conservi l’ultimo pagamento riuscito
T, programma il tentativo successivo all’T + X daysper mantenere l’allineamento con l’orario del giorno.
Fuso orario e ora legale: usa uno standard temporale coerente per la pianificazione e converti solo per la visualizzazione, per mantenere gli intervalli.
Codici di rifiuto che non dovresti ripetere
STOLEN_CARDDO_NOT_HONORFRAUDULENTPICKUP_CARDAUTHENTICATION_FAILURELOST_CARD
Per un elenco completo dei motivi di rifiuto e se sono correggibili dall’utente, consulta la documentazione su
Transaction Failures.
Linee guida per l’implementazione (senza codice)
- Usa un scheduler/queue che conservi timestamp precisi; calcola il prossimo tentativo allo stesso offset orario (es.
T + 3 daysalla stessa HH:MM). - Mantieni e fai riferimento all’ultimo timestamp di pagamento riuscito
Tper calcolare il tentativo successivo; non concentrare più abbonamenti nello stesso istante. - Valuta sempre l’ultimo motivo di rifiuto; interrompi i retry per i rifiuti hard nella lista di esclusione sopra.
- Limita i retry concorrenti per cliente e per account per evitare picchi accidentali.
- Comunica proattivamente: invia email/SMS al cliente per aggiornare il metodo di pagamento prima del prossimo tentativo programmato.
- Usa i metadata solo per l’osservabilità (es.
retry_attempt); non cercare di «eludere» i sistemi antifrode/rischio ruotando campi irrilevanti.
Monitora i risultati con i webhook
Implementa la gestione dei webhook per monitorare il percorso del cliente. Consulta Implementazione dei webhook.- subscription.active: Mandato autorizzato e sottoscrizione attivata
- subscription.failed: Creazione fallita (ad es., fallimento del mandato)
- subscription.on_hold: Sottoscrizione messa in attesa (ad es., stato non pagato)
- payment.succeeded: Addebito riuscito
- payment.failed: Addebito fallito
Test e prossimi passi
Create in test mode
Usa la tua chiave API di test per creare l’abbonamento con
payment_link: true, poi apri il link e completa il mandato.Trigger a charge
Chiama l’endpoint degli addebiti con un piccolo
product_price (es. 100) e verifica di ricevere payment.succeeded.Risoluzione dei problemi
- 422 Invalid Request: Assicurati che
on_demand.mandate_onlyvenga fornito alla creazione eproduct_pricevenga fornito per gli addebiti. - Errori di valuta: Se sovrascrivi
product_currency, conferma che sia supportato per il tuo account e cliente. - Nessun webhook ricevuto: Verifica la configurazione del tuo URL webhook e del segreto di firma.