Abbonamenti On-Demand

​

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 una sottoscrizione con l’oggetto on_demand per autorizzare un metodo di pagamento e, facoltativamente, raccogliere un addebito iniziale.
2. In seguito, crei addebiti contro quella sottoscrizione con importi personalizzati utilizzando l’endpoint di addebito dedicato.
3. Ascolti i webhook (ad 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" }

​

Riprova ai pagamenti

​

Principi per politiche di ripetizione sicure

• Meccanismo di backoff: Usa il backoff esponenziale tra le ripetizioni.
• Limiti di ripetizione: Limita il totale delle ripetizioni (massimo 3-4 tentativi).
• Filtraggio intelligente: Ripeti solo in caso di errori ripetibili (ad es., errori di rete/emittente, fondi insufficienti); non ripetere mai i rifiuti definitivi.
• Prevenzione dei test di carte: Non ripetere i rifiuti come DO_NOT_HONOR, STOLEN_CARD, LOST_CARD, PICKUP_CARD, FRAUDULENT, AUTHENTICATION_FAILURE.
• Variazione dei metadati (opzionale): Se mantieni il tuo sistema di ripetizione, differenzia le ripetizioni tramite metadati (ad 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 le ripetizioni all’ora di autorizzazione originale per evitare comportamenti a “raffica” nel tuo portafoglio.
• Esempio: Se il cliente inizia 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 es., +3 giorni → 13:10, +7 giorni → 13:10).
• In alternativa, se memorizzi l’ora dell’ultimo pagamento riuscito T, programma il prossimo tentativo a T + X days per preservare l’allineamento dell’ora del giorno.

​

Codici di rifiuto che non dovresti ripetere

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

​

Linee guida per l’implementazione (senza codice)

• Usa un pianificatore/coda che persiste timestamp precisi; calcola il prossimo tentativo all’orario esatto (ad es., T + 3 days alla stessa HH:MM).
• Mantieni e fai riferimento all’ora dell’ultimo pagamento riuscito T per calcolare il prossimo tentativo; non raggruppare più sottoscrizioni nello stesso istante.
• Valuta sempre l’ultima motivazione di rifiuto; interrompi le ripetizioni per i rifiuti definitivi nell’elenco di esclusione sopra.
• Limita le ripetizioni concorrenti per cliente e per account per prevenire picchi accidentali.
• Comunica in modo proattivo: invia un’email/SMS al cliente per aggiornare il proprio metodo di pagamento prima del prossimo tentativo programmato.
• Usa i metadati solo per l’osservabilità (ad es., retry_attempt); non cercare mai di “evadere” i sistemi di frode/rischio ruotando campi irrilevanti.

​

Monitora i risultati con i 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

​

Risoluzione dei problemi

• 422 Richiesta non valida: Assicurati che on_demand.mandate_only sia fornito alla 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 l’URL del tuo webhook e la configurazione del segreto della firma.