Abbonamenti On-Demand

Documentation Index

Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Panoramica

• 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

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

​

Crea una sottoscrizione on-demand

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 subscription = await client.checkoutSessions.create({
    product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
    billing_address:  { city: 'SF', country: 'US', state: 'CA', street: '1 Market St', zipcode: '94105' },
    customer: { customer_id: 'cus_123' },
    return_url: 'https://example.com/billing/success',
    subscription_data: {
        on_demand: {
            mandate_only: true // set false to collect an initial charge
            // product_price: 1000, // optional: charge $10.00 now if mandate_only is false
            // product_currency: 'USD',
            // product_description: 'Custom initial charge',
            // adaptive_currency_fees_inclusive: false,
        }
    }
  });

  console.log(subscription.checkout_url);
}

main().catch(console.error);

import os
from dodopayments import DodoPayments

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

checkout = client.checkout_sessions.create(
    product_cart=[
        {"product_id": "pdt_123", "quantity": 1}
    ],
    billing_address={
        "city": "SF",
        "country": "US",
        "state": "CA",
        "street": "1 Market St",
        "zipcode": "94105",
    },
    customer={
        "customer_id": "cus_123",
    },
    return_url="https://example.com/billing/success",
    subscription_data={
      "on_demand":{
      "mandate_only": True,  # set False to collect an initial charge
      # "product_price": 1000,  # optional: charge $10.00 now if mandate_only is false
      # "product_currency": "USD",
      # "product_description": "Custom initial charge",
      # "adaptive_currency_fees_inclusive": False,
      }
    },
)

print(checkout.checkout_url)

package main

import (
    "fmt"
    "os"

    dodo "github.com/dodopayments/dodopayments-go"
)

func main() {
    client := dodo.NewClient(dodo.Config{
        BearerToken: os.Getenv("DODO_PAYMENTS_API_KEY"),
        Environment: dodo.TestMode, // defaults to LiveMode
    })

    checkout, err := client.CheckoutSessions.Create(dodo.CheckoutSessionCreateParams{
        ProductCart: []dodo.ProductCartItem{
            {
                ProductID: "pdt_123",
                Quantity:  1,
            },
        },
        BillingAddress: &dodo.BillingAddress{
            City:    "SF",
            Country: "US",
            State:   "CA",
            Street:  "1 Market St",
            Zipcode: "94105",
        },
        Customer: &dodo.CustomerRef{
            CustomerID: "cus_123",
        },
        ReturnURL: "https://example.com/billing/success",
        SubscriptionData: &dodo.SubscriptionData{
            OnDemand: &dodo.OnDemandSubscription{
                MandateOnly: true, // set false to collect an initial charge
                // ProductPrice: 1000,  // optional: charge $10.00 now if mandate_only is false
                // ProductCurrency: "USD",
                // ProductDescription: "Custom initial charge",
                // AdaptiveCurrencyFeesInclusive: false,
            },
        },
    })
    if err != nil {
        panic(err)
    }

    fmt.Println(checkout.CheckoutURL)
}

curl -X POST "$DODO_API/checkouts" \
  -H "Authorization: Bearer $DODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_cart": [
      {
        "product_id": "pdt_123",
        "quantity": 1
      }
    ],
    "customer": {
      "customer_id": "cus_123"
    },
    "billing_address": {
      "street": "1 Market St",
      "city": "SF",
      "state": "CA",
      "country": "US",
      "zipcode": "94105"
    },
    "subscription_data": {
      "on_demand": {
        "mandate_only": true
      }
    },
    "return_url": "https://example.com/billing/success"
  }'

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

​

Addebita una sottoscrizione on-demand

import DodoPayments from 'dodopayments';

const client = new DodoPayments({ bearerToken: process.env.DODO_PAYMENTS_API_KEY });

async function chargeNow(subscriptionId) {
  const res = await client.subscriptions.charge(subscriptionId, { product_price: 2500 });
  console.log(res.payment_id);
}

chargeNow('sub_123').catch(console.error);

import os
from dodopayments import DodoPayments

client = DodoPayments(bearer_token=os.environ.get('DODO_PAYMENTS_API_KEY'))

response = client.subscriptions.charge(
    subscription_id="sub_123",
    product_price=2500,
)

print(response.payment_id)

package main

import (
  "context"
  "fmt"
  "github.com/dodopayments/dodopayments-go"
  "github.com/dodopayments/dodopayments-go/option"
)

func main() {
  client := dodopayments.NewClient(option.WithBearerToken("YOUR_API_KEY"))
  res, err := client.Subscriptions.Charge(context.TODO(), "sub_123", dodopayments.SubscriptionChargeParams{
    ProductPrice: dodopayments.F(int64(2500)),
  })
  if err != nil { panic(err) }
  fmt.Println(res.PaymentID)
}

curl -X POST "$DODO_API/subscriptions/sub_123/charge" \
  -H "Authorization: Bearer $DODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_price": 2500,
    "product_description": "Extra usage for March"
  }'

{ "payment_id": "pay_abc123" }

​

Gestione delle transazioni fallite

​

Cosa succede in caso di fallimento

​

Sequenza di webhook su un addebito su richiesta fallito

​

Responsabilità della ripetizione

​

Ripetizione dei pagamenti

​

Principi per politiche di ripetizione sicure

• Meccanismo di backoff: Usa un backoff esponenziale tra le ripetizioni.
• Limiti di ripetizione: Limita le ripetizioni totali (max 3–4 tentativi).
• Filtraggio intelligente: Ripeti solo su fallimenti ripetibili (ad esempio, errori di rete/emittente, fondi insufficienti); non riprovare mai per rifiuti rigidi.
• Prevenzione del test di carte: Non riprovare fallimenti come DO_NOT_HONOR, STOLEN_CARD, LOST_CARD, PICKUP_CARD, FRAUDULENT, AUTHENTICATION_FAILURE.
• Varietà di metadata (opzionale): Se mantieni il tuo sistema di ripetizione, differenzia le ripetizioni tramite metadata (ad esempio, retry_attempt).

​

Programma di ripetizione suggerito (abbonamenti)

• 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)

​

Evitare ripetizioni a raffica; allinea al tempo di autorizzazione

• Ancora le ripetizioni al timestamp di autorizzazione originale per evitare comportamenti a “raffica” su tutto il portafoglio.
• Esempio: Se il cliente avvia una prova o un mandato alle 13:10 di oggi, programma le ripetizioni successive alle 13:10 nei giorni successivi secondo il tuo backoff (ad esempio, +3 giorni → 13:10, +7 giorni → 13:10).
• In alternativa, se memorizzi l’ora dell’ultimo pagamento riuscito T, programma il tentativo successivo a T + X days per preservare l’allineamento dell’orario.

​

Codici di declino che non dovresti riprovare

• STOLEN_CARD
• DO_NOT_HONOR
• FRAUDULENT
• PICKUP_CARD
• AUTHENTICATION_FAILURE
• LOST_CARD

​

Linee guida per l’implementazione (senza codice)

• Utilizza un gestore di code che mantiene timestamp precisi; calcola il tentativo successivo all’esatto offset orario (ad esempio, T + 3 days alla stessa HH:MM).
• Mantieni e riferisci il timestamp dell’ultimo pagamento riuscito T per calcolare il tentativo successivo; non raggruppare più abbonamenti allo stesso istante.
• Valuta sempre il motivo dell’ultimo declino; interrompi le ripetizioni per declini rigidi nella lista di skip sopra.
• Limita le ripetizioni concorrenti per cliente e per account per prevenire picchi accidentali.
• Comunica proattivamente: invia email/SMS al cliente per aggiornare il metodo di pagamento prima del prossimo tentativo programmato.
• Usa metadata solo per osservabilità (ad esempio, retry_attempt); non cercare mai di “evadere” i sistemi di frode/rischio ruotando campi irrilevanti.

​

Tracciare i risultati con i webhook

• subscription.active: Mandato autorizzato e abbonamento attivato
• subscription.failed: Creazione fallita (ad esempio, fallimento del mandato)
• subscription.on_hold: Abbonamento sospeso (ad esempio, stato non pagato)
• payment.succeeded: Addebito riuscito
• payment.failed: Addebito fallito

​

Test e passaggi successivi

​

Risoluzione dei problemi

• 422 Richiesta non valida: Assicurati che on_demand.mandate_only sia fornito in fase di creazione e product_price sia 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.