Guida all'integrazione degli abbonamenti

​

Requisiti

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

​

Integrazione API

​

Sessioni di Checkout

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: '[email protected]',
      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": "[email protected]",
        "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: '[email protected]',
      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

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

​

Webhook

​

Tipi di eventi di abbonamento

1. subscription.active - L’abbonamento è stato attivato con successo.
2. subscription.updated - L’oggetto abbonamento è stato aggiornato (si attiva su qualsiasi modifica di campo).
3. subscription.on_hold - L’abbonamento è stato messo in attesa a causa di un rinnovo non riuscito.
4. subscription.failed - La creazione dell’abbonamento è fallita durante la creazione del mandato.
5. subscription.renewed - L’abbonamento è stato rinnovato per il prossimo periodo di fatturazione.

​

Scenari di pagamento

1. subscription.active - Indica l’attivazione dell’abbonamento
2. payment.succeeded - Conferma il pagamento iniziale:
   • Per la fatturazione immediata (0 giorni di prova): Aspettati entro 2-10 minuti
   • Per i giorni di prova: ogni volta che termina
3. subscription.renewed - Indica la deduzione del pagamento e il rinnovo per il prossimo ciclo. (Fondamentalmente, ogni volta che il pagamento viene dedotto per i prodotti in abbonamento, riceverai il webhook subscription.renewed insieme a payment.succeeded)

1. Fallimento dell’abbonamento

• subscription.failed - La creazione dell’abbonamento è fallita a causa del fallimento nella creazione di un mandato.
• payment.failed - Indica un pagamento non riuscito.

2. Abbonamento in attesa

• subscription.on_hold - L’abbonamento è stato messo in attesa a causa di un pagamento di rinnovo non riuscito o di un addebito di cambio piano non riuscito.
• Quando un abbonamento viene messo in attesa, non si rinnoverà automaticamente fino a quando il metodo di pagamento non verrà aggiornato.

​

Gestione dell’abbonamento in attesa

​

Quando gli abbonamenti vengono messi in attesa

• 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

​

Riattivazione degli abbonamenti in attesa

1. Crea un addebito per i restanti importi dovuti
2. Genera una fattura per l’addebito
3. Elabora il pagamento utilizzando il nuovo metodo di pagamento
4. Riattiva l’abbonamento nello stato di active dopo un pagamento riuscito

// 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 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
}

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

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

​

Cambiare i piani di abbonamento

​

Opzioni di Prorata

​

1. prorated_immediately

• Calcola l’importo prorato in base al tempo rimanente nel ciclo di fatturazione attuale
• Addebita al cliente solo la differenza tra il vecchio e il nuovo piano
• Durante un periodo di prova, questo cambierà immediatamente l’utente al nuovo piano, addebitando il cliente subito

​

2. full_immediately

• Addebita al cliente l’importo totale dell’abbonamento per il nuovo piano
• Ignora qualsiasi tempo rimanente o crediti dal piano precedente
• Utile quando vuoi ripristinare il ciclo di fatturazione o addebitare l’importo totale indipendentemente dalla proration

​

3. difference_immediately

• Quando si aggiorna, al cliente viene immediatamente addebitata la differenza tra i due importi del piano.
• Ad esempio, se il piano attuale è di 30 Dollari e il cliente passa a un piano di 80 Dollari, viene addebitato $50 immediatamente.
• Quando si riduce, l’importo non utilizzato dal piano attuale viene aggiunto come credito interno e applicato automaticamente ai futuri rinnovi dell’abbonamento.
• Ad esempio, se il piano attuale è di 50 Dollari e il cliente passa a un piano di 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 in base all’opzione di proration selezionata
• Se il cambio piano è una riduzione e utilizzi prorated_immediately, i crediti verranno calcolati automaticamente e aggiunti al saldo di credito 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 salta i calcoli di credito e addebita l’intero importo del nuovo piano

​

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