Guida all'integrazione degli abbonamenti

Requisiti

Per integrare l’API di Dodo Payments, avrai bisogno di:

Un account commerciante Dodo Payments
Credenziali API (chiave API e chiave segreta webhook) dal dashboard

Per una guida più dettagliata sui requisiti, controlla questa sezione.

Integrazione API

Sessioni di Checkout

Utilizza le Checkout Sessions per vendere prodotti in abbonamento con un checkout ospitato sicuro. Includi il tuo prodotto in abbonamento in product_cart e reindirizza i clienti al valore restituito checkout_url.

Checkout misto: puoi combinare prodotti in abbonamento con prodotti una tantum nella stessa sessione di checkout. Questo abilita casi d’uso come commissioni di configurazione con abbonamenti, pacchetti hardware con SaaS e altro ancora. Consulta la guida alle Checkout Sessions per esempi.

Node.js SDK
Python SDK
REST API

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

async function main() {
  const session = await client.checkoutSessions.create({
    product_cart: [
      { product_id: 'prod_subscription_monthly', quantity: 1 }
    ],
    // Optional: configure trials for subscription products
    subscription_data: { trial_period_days: 14 },
    customer: {
      email: 'subscriber@example.com',
      name: 'Jane Doe',
    },
    return_url: 'https://example.com/success',
  });

  console.log(session.checkout_url);
}

main();

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",  # defaults to "live_mode"
)

session = client.checkout_sessions.create(
    product_cart=[
        {"product_id": "prod_subscription_monthly", "quantity": 1}
    ],
    subscription_data={"trial_period_days": 14},  # optional
    customer={
        "email": "subscriber@example.com",
        "name": "Jane Doe",
    },
    return_url="https://example.com/success",
)

print(session.checkout_url)

const response = await fetch('https://test.dodopayments.com/checkouts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`
  },
  body: JSON.stringify({
    product_cart: [
      { product_id: 'prod_subscription_monthly', quantity: 1 }
    ],
    subscription_data: { trial_period_days: 14 }, // optional
    customer: {
      email: 'subscriber@example.com',
      name: 'Jane Doe'
    },
    return_url: 'https://example.com/success'
  })
});

if (!response.ok) {
  throw new Error(`HTTP error! status: ${response.status}`);
}

const session = await response.json();
console.log(session.checkout_url);

Risposta API

Di seguito è riportato un esempio della risposta:

{
  "session_id": "cks_Gi6KGJ2zFJo9rq9Ukifwa",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}

Reindirizza il cliente a checkout_url.

Webhook

Quando integri gli abbonamenti, riceverai webhook per tracciare il ciclo di vita dell’abbonamento. Questi webhook ti aiutano a gestire efficacemente gli stati degli abbonamenti e gli scenari di pagamento. Per configurare il tuo endpoint webhook, segui la nostra Guida all’integrazione dettagliata.

Tipi di eventi di abbonamento

I seguenti eventi webhook tracciano le modifiche di stato dell’abbonamento:

subscription.active - L’abbonamento è stato attivato con successo.
subscription.updated - L’oggetto abbonamento è stato aggiornato (scatena l’evento per qualsiasi modifica al campo).
subscription.on_hold - L’abbonamento viene sospeso a causa di un rinnovo non riuscito.
subscription.failed - La creazione dell’abbonamento non è riuscita durante la creazione del mandato.
subscription.renewed - L’abbonamento viene rinnovato per il prossimo periodo di fatturazione.

Per una gestione affidabile del ciclo di vita degli abbonamenti, ti consigliamo di tracciare questi eventi di abbonamento.

Usa subscription.updated per ricevere notifiche in tempo reale su qualsiasi modifica all’abbonamento e mantenere lo stato dell’applicazione sincronizzato senza interrogare periodicamente l’API.

Scenari di pagamento

Flusso di pagamento riuscito Quando un pagamento ha successo, riceverai i seguenti webhook:

subscription.active - Indica l’attivazione dell’abbonamento
payment.succeeded - Conferma il pagamento iniziale:
- Per la fatturazione immediata (0 giorni di prova): previsto entro 2-10 minuti
- Per i giorni di prova: non appena terminano
subscription.renewed - Indica l’addebito e il rinnovo per il ciclo successivo. (In pratica, ogni volta che viene addebitato un pagamento per prodotti in abbonamento, riceverai subscription.renewed oltre a payment.succeeded)

Scenari di pagamento non riusciti

Mancato pagamento dell’abbonamento

subscription.failed - La creazione dell’abbonamento è fallita per impossibilità di creare un mandato.
payment.failed - Indica un pagamento non riuscito.

Abbonamento in sospeso

subscription.on_hold - L’abbonamento viene messo in sospeso a causa di un rinnovo o di un addebito per cambio piano non riuscito.
Quando un abbonamento viene sospeso, non si rinnova automaticamente finché non viene aggiornato il metodo di pagamento.

Best Practice: per semplificare l’implementazione, consigliamo di monitorare principalmente gli eventi relativi all’abbonamento per gestire il ciclo di vita dell’abbonamento.

Gestione dell’abbonamento in attesa

Quando un abbonamento entra nello stato on_hold, è necessario aggiornare il metodo di pagamento per riattivarlo. Questa sezione spiega quando gli abbonamenti vengono messi in sospeso e come gestirli.

Quando gli abbonamenti vengono messi in attesa

Un abbonamento viene messo in attesa quando:

Il pagamento di rinnovo non riesce: L’addebito di rinnovo automatico fallisce a causa di fondi insufficienti, carta scaduta o rifiuto della banca
Il pagamento per cambio piano non riesce: Un addebito immediato durante l’aggiornamento/downgrade del piano fallisce
L’autorizzazione del metodo di pagamento fallisce: Il metodo di pagamento non può essere autorizzato per addebiti ricorrenti

Gli abbonamenti in stato on_hold non si rinnovano automaticamente. Devi aggiornare il metodo di pagamento per riattivare l’abbonamento.

Riattivazione degli abbonamenti in attesa

Per riattivare un abbonamento dallo stato on_hold, usa l’API Update Payment Method. Questa operazione effettua automaticamente:

Crea un addebito per gli importi residui
Genera una fattura per tale addebito
Elabora il pagamento utilizzando il nuovo metodo
Riattiva l’abbonamento nello stato active al completamento del pagamento

Handle subscription.on_hold webhook

Quando ricevi un webhook subscription.on_hold, aggiorna lo stato dell’applicazione e avvisa il cliente:

// Webhook handler
app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;
  
  if (event.type === 'subscription.on_hold') {
    const subscription = event.data;
    
    // Update subscription status in your database
    await updateSubscriptionStatus(subscription.subscription_id, 'on_hold');
    
    // Notify customer to update payment method
    await sendEmailToCustomer(subscription.customer_id, {
      subject: 'Payment Required - Subscription On Hold',
      message: 'Your subscription is on hold. Please update your payment method to continue service.'
    });
  }
  
  res.json({ received: true });
});

Update payment method

Quando il cliente è pronto per aggiornare il metodo di pagamento, chiama l’API Update Payment Method:

// Update with new payment method
const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
  type: 'new',
  return_url: 'https://example.com/return'
});

// For on_hold subscriptions, a charge is automatically created
if (response.payment_id) {
  console.log('Charge created for remaining dues:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
}

Puoi anche usare un ID di metodo di pagamento esistente se il cliente ha metodi salvati:

await client.subscriptions.updatePaymentMethod(subscriptionId, {
  type: 'existing',
  payment_method_id: 'pm_abc123'
});

Monitor webhook events

Dopo aver aggiornato il metodo di pagamento, monitora questi eventi webhook:

payment.succeeded - L’addebito per gli importi residui è stato completato con successo
subscription.active - L’abbonamento è stato riattivato

if (event.type === 'payment.succeeded') {
  const payment = event.data;
  
  // Check if this payment is for an on_hold subscription
  if (payment.subscription_id) {
    // Wait for subscription.active webhook to confirm reactivation
  }
}

if (event.type === 'subscription.active') {
  const subscription = event.data;
  
  // Update subscription status in your database
  await updateSubscriptionStatus(subscription.subscription_id, 'active');
  
  // Restore customer access
  await restoreCustomerAccess(subscription.customer_id);
  
  // Notify customer of successful reactivation
  await sendEmailToCustomer(subscription.customer_id, {
    subject: 'Subscription Reactivated',
    message: 'Your subscription has been reactivated successfully.'
  });
}

Payload dell’evento di abbonamento di esempio

Proprietà	Tipo	Richiesto	Descrizione
`business_id`	stringa	Sì	L’identificatore univoco per l’azienda
`timestamp`	stringa	Sì	Il timestamp di quando si è verificato l’evento (non necessariamente lo stesso momento della consegna)
`type`	stringa	Sì	Il tipo di evento. Consulta Event Types
`data`	oggetto	Sì	Il payload dati principale. Consulta Data Object

Cambiare i piani di abbonamento

Puoi aggiornare o ridurre un piano di abbonamento utilizzando l’endpoint API di cambio piano. Questo ti consente di modificare il prodotto dell’abbonamento, la quantità e gestire la proration.

Change Plan API Reference

Per informazioni dettagliate sulla modifica dei piani di abbonamento, consulta la nostra documentazione sull’API Change Plan.

Opzioni di Prorata

Quando cambi i piani di abbonamento, hai due opzioni per gestire l’addebito immediato:

1. `prorated_immediately`

Calcola l’importo proporzionale in base al tempo rimanente nel ciclo di fatturazione corrente
Addebita al cliente solo la differenza tra il piano precedente e quello nuovo
Durante un periodo di prova, questo comporterà l’immediato passaggio dell’utente al nuovo piano, addebitando subito il cliente

2. `full_immediately`

Addebita al cliente l’intero importo dell’abbonamento per il nuovo piano
Ignora il tempo rimanente o i crediti residui del piano precedente
Utile quando si desidera resettare il ciclo di fatturazione o addebitare l’importo totale indipendentemente dalla proratizzazione

3. `difference_immediately`

Quando si esegue un upgrade, il cliente viene addebitato immediatamente la differenza tra i due importi del piano.
Ad esempio, se il piano attuale è di 30 dollari e il cliente passa a 80 dollari, viene addebitato $50 immediatamente.
Quando si esegue un downgrade, l’importo inutilizzato del piano corrente viene aggiunto come credito interno e applicato automaticamente ai successivi rinnovi dell’abbonamento.
Ad esempio, se il piano corrente è di 50 dollari e il cliente passa a un piano da 20 dollari, i restanti $30 vengono accreditati e utilizzati per il prossimo ciclo di fatturazione.

Comportamento

Quando invochi questa API, Dodo Payments avvia immediatamente un addebito basato sull’opzione di proratizzazione selezionata
Se il cambio piano è un downgrade e utilizzi prorated_immediately, i crediti verranno calcolati automaticamente e aggiunti al saldo crediti dell’abbonamento. Questi crediti sono specifici per quell’abbonamento e verranno utilizzati solo per compensare i futuri pagamenti ricorrenti dello stesso abbonamento
L’opzione full_immediately bypassa il calcolo dei crediti e addebita l’intero importo del nuovo piano

Scegli con attenzione l’opzione di proratizzazione: utilizza prorated_immediately per una fatturazione equa che tenga conto del tempo non utilizzato, o full_immediately quando desideri addebitare l’intero importo del nuovo piano indipendentemente dal ciclo di fatturazione corrente.

Elaborazione degli addebiti

L’addebito immediato avviato al momento del cambio piano di solito completa l’elaborazione in meno di 2 minuti
Se questo addebito immediato fallisce per qualsiasi motivo, l’abbonamento viene automaticamente messo in attesa fino a quando il problema non viene risolto

Abbonamenti On-Demand

Gli abbonamenti on-demand consentono di addebitare i clienti in modo flessibile, non solo su un programma fisso. Questa funzione è disponibile per tutti gli account.

Per creare un abbonamento on-demand: Per creare un abbonamento on-demand, usa l’endpoint API POST /subscriptions e includi il campo on_demand nel body della richiesta. Questo ti permette di autorizzare un metodo di pagamento senza un addebito immediato o impostare un prezzo iniziale personalizzato. Per addebitare un abbonamento on-demand: Per addebiti successivi, utilizza l’endpoint POST /subscriptions/charge e specifica l’importo da addebitare al cliente per quella transazione.

Per una guida completa passo dopo passo—including esempi di richieste/risposte, politiche di retry sicure e gestione dei webhook—consulta la Guida agli abbonamenti on-demand.

Integration Guides

Billing Deconstructions

Cookbooks

Requisiti

Integrazione API

Sessioni di Checkout

Risposta API

Webhook

Tipi di eventi di abbonamento

Scenari di pagamento

Gestione dell’abbonamento in attesa

Quando gli abbonamenti vengono messi in attesa

Riattivazione degli abbonamenti in attesa

Payload dell’evento di abbonamento di esempio

Cambiare i piani di abbonamento

Change Plan API Reference

Opzioni di Prorata

1. `prorated_immediately`

2. `full_immediately`

3. `difference_immediately`

Comportamento

Elaborazione degli addebiti

Abbonamenti On-Demand

Integration Guides

Billing Deconstructions

Cookbooks

​Requisiti

​Integrazione API

​Sessioni di Checkout

​Risposta API

​Webhook

​Tipi di eventi di abbonamento

​Scenari di pagamento

​Gestione dell’abbonamento in attesa

​Quando gli abbonamenti vengono messi in attesa

​Riattivazione degli abbonamenti in attesa

​Payload dell’evento di abbonamento di esempio

​Cambiare i piani di abbonamento

Change Plan API Reference

​Opzioni di Prorata

​1. prorated_immediately

​2. full_immediately

​3. difference_immediately

​Comportamento

​Elaborazione degli addebiti

​Abbonamenti On-Demand

Requisiti

Integrazione API

Sessioni di Checkout

Risposta API

Webhook

Tipi di eventi di abbonamento

Scenari di pagamento

Gestione dell’abbonamento in attesa

Quando gli abbonamenti vengono messi in attesa

Riattivazione degli abbonamenti in attesa

Payload dell’evento di abbonamento di esempio

Cambiare i piani di abbonamento

Opzioni di Prorata

1. `prorated_immediately`

2. `full_immediately`

3. `difference_immediately`

Comportamento

Elaborazione degli addebiti

Abbonamenti On-Demand