Abbonamenti On-Demand

​

Panoramica

• Creare un abbonamento on-demand (autorizzare un mandato con prezzo iniziale opzionale)
• Attivare addebiti successivi con importi personalizzati
• Monitorare i risultati utilizzando 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, raccogliere un addebito iniziale.
2. In seguito, crei addebiti contro quell’abbonamento 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 un abbonamento on-demand

​

Crea un abbonamento 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.subscriptions.create({
    billing: { city: 'SF', country: 'US', state: 'CA', street: '1 Market St', zipcode: '94105' },
    customer: { customer_id: 'customer_123' },
    product_id: 'prod_sub_123',
    quantity: 1,
    payment_link: true,
    return_url: 'https://example.com/billing/success',
    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,
    },
  });

  // If payment_link was true, redirect the customer to authorize the mandate
  console.log(subscription.payment_link);
}

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

subscription = client.subscriptions.create(
    billing={
        "city": "SF",
        "country": "US",
        "state": "CA",
        "street": "1 Market St",
        "zipcode": "94105",
    },
    customer={"customer_id": "customer_123"},
    product_id="prod_sub_123",
    quantity=1,
    payment_link=True,
    return_url="https://example.com/billing/success",
    on_demand={
        "mandate_only": True,
        # "product_price": 1000,
        # "product_currency": "USD",
        # "product_description": "Custom initial charge",
        # "adaptive_currency_fees_inclusive": False,
    },
)

print(subscription.payment_link)

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"),
  )
  subscription, err := client.Subscriptions.New(context.TODO(), dodopayments.SubscriptionNewParams{
    Billing: dodopayments.F(dodopayments.BillingAddressParam{
      City:    dodopayments.F("SF"),
      Country: dodopayments.F(dodopayments.CountryCodeUs),
      State:   dodopayments.F("CA"),
      Street:  dodopayments.F("1 Market St"),
      Zipcode: dodopayments.F("94105"),
    }),
    Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](dodopayments.AttachExistingCustomerParam{
      CustomerID: dodopayments.F("customer_123"),
    }),
    ProductID:  dodopayments.F("prod_sub_123"),
    Quantity:   dodopayments.F(int64(1)),
    PaymentLink: dodopayments.F(true),
    ReturnURL:   dodopayments.F("https://example.com/billing/success"),
    OnDemand: dodopayments.F(dodopayments.OnDemandSubscriptionReqParam{
      MandateOnly: dodopayments.F(true),
      // ProductPrice: dodopayments.F(int64(1000)),
      // ProductCurrency: dodopayments.F(dodopayments.CurrencyUsd),
      // ProductDescription: dodopayments.F("Custom initial charge"),
      // AdaptiveCurrencyFeesInclusive: dodopayments.F(false),
    }),
  })
  if err != nil { panic(err) }
  fmt.Println(subscription.PaymentLink)
}

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

{
  "subscription_id": "sub_123",
  "payment_link": "https://pay.dodopayments.com/checkout/...",
  "customer": { "customer_id": "customer_123", "email": "[email protected]", "name": "Alex Doe" },
  "metadata": {},
  "recurring_pre_tax_amount": 0,
  "addons": []
}

​

Addebita un abbonamento 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 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'),
    environment="test_mode",  # defaults to "live_mode"
)

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

​

Evita ripetizioni a raffica; allineati all’orario di autorizzazione

• Ancorare le ripetizioni al timestamp 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, pianifica 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, pianifica 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’esatto offset dell’ora del giorno (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ù abbonamenti 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 proattivamente: 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 insignificanti.

​

Monitora i risultati con i webhook

• subscription.active: Mandato autorizzato e abbonamento attivato
• subscription.failed: Creazione fallita (ad es., fallimento del mandato)
• subscription.on_hold: Abbonamento messo 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 che 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.