On-Demand-Abonnements

​

Übersicht

• Ein On-Demand-Abonnement zu erstellen (ein Mandat mit optionalem Anfangspreis zu autorisieren)
• Nachfolgende Zahlungen mit benutzerdefinierten Beträgen auszulösen
• Ergebnisse mithilfe von Webhooks zu verfolgen

​

Voraussetzungen

• Dodo Payments-Händlerkonto und API-Schlüssel
• Webhook-Geheimnis konfiguriert und einen Endpunkt zum Empfangen von Ereignissen
• Ein Abonnementprodukt in Ihrem Katalog

​

So funktioniert On-Demand

1. Sie erstellen ein Abonnement mit dem on_demand-Objekt, um eine Zahlungsmethode zu autorisieren und optional eine Anfangsbelastung einzuziehen.
2. Später lösen Sie Belastungen gegen dieses Abonnement mit benutzerdefinierten Beträgen über den dedizierten Charge-Endpunkt aus.
3. Sie hören auf Webhooks (z. B. payment.succeeded, payment.failed), um Ihr System zu aktualisieren.

​

Erstellen Sie ein On-Demand-Abonnement

​

Erstellen Sie ein On-Demand-Abonnement

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

​

Berechnen Sie ein On-Demand-Abonnement

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

​

Zahlungswiederholungen

​

Grundsätze für sichere Wiederholungsrichtlinien

• Backoff-Mechanismus: Verwenden Sie exponentielles Backoff zwischen Wiederholungen.
• Retry-Begrenzung: Beschränken Sie die Gesamtanzahl der Wiederholungen (max. 3–4 Versuche).
• Intelligente Filterung: Wiederholen Sie nur bei retryfähigen Fehlern (z. B. Netzwerk-/Issuer-Fehler, unzureichende Mittel); wiederholen Sie niemals bei harten Ablehnungen.
• Verhinderung von Kartentests: Wiederholen Sie keine Fehler wie DO_NOT_HONOR, STOLEN_CARD, LOST_CARD, PICKUP_CARD, FRAUDULENT, AUTHENTICATION_FAILURE.
• Metadaten variieren (optional): Wenn Sie ein eigenes Retry-System pflegen, unterscheiden Sie Wiederholungen über Metadaten (z. B. retry_attempt).

​

Vorgeschlagener Wiederholungszeitplan (Abonnements)

• 1. Versuch: Sofort, wenn Sie die Zahlung erstellen
• 2. Versuch: Nach 3 Tagen
• 3. Versuch: Nach weiteren 7 Tagen (insgesamt 10 Tage)
• 4. Versuch (final): Nach weiteren 7 Tagen (insgesamt 17 Tage)

​

Vermeiden Sie gebündelte Wiederholungen; richten Sie sich nach der Autorisierungszeit

• Verankern Sie Wiederholungen am ursprünglichen Autorisierungszeitpunkt, um “Burst”-Verhalten in Ihrem Portfolio zu vermeiden.
• Beispiel: Wenn der Kunde heute um 13:10 Uhr eine Testphase oder ein Mandat startet, planen Sie nachfolgende Wiederholungen für 13:10 Uhr an den folgenden Tagen gemäß Ihrem Backoff (z. B. +3 Tage → 13:10 Uhr, +7 Tage → 13:10 Uhr).
• Alternativ: Wenn Sie den Zeitpunkt der letzten erfolgreichen Zahlung T speichern, planen Sie den nächsten Versuch um T + X days, um die Time-of-Day-Ausrichtung beizubehalten.

​

Ablehnungscodes, die Sie nicht wiederholen sollten

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

​

Implementierungsrichtlinien (kein Code)

• Verwenden Sie einen Scheduler/Queue, der präzise Zeitstempel speichert; berechnen Sie den nächsten Versuch genau zum gleichen Tageszeiten-Offset (z. B. T + 3 days zur gleichen HH:MM).
• Pflegen und verwenden Sie den Zeitstempel der letzten erfolgreichen Zahlung T zur Berechnung des nächsten Versuchs; bündeln Sie nicht mehrere Abonnements zum selben Zeitpunkt.
• Bewerten Sie immer den letzten Ablehnungsgrund; stoppen Sie Wiederholungen bei harten Ablehnungen aus der oben genannten Ausnahmeliste.
• Begrenzen Sie gleichzeitige Wiederholungen pro Kunde und pro Konto, um unbeabsichtigte Spitzen zu vermeiden.
• Kommunizieren Sie proaktiv: Informieren Sie den Kunden per E-Mail/SMS, dass er seine Zahlungsmethode vor dem nächsten geplanten Versuch aktualisieren soll.
• Verwenden Sie Metadaten nur zur Beobachtbarkeit (z. B. retry_attempt); versuchen Sie niemals, Betrugs-/Risikosysteme zu “umgehen”, indem Sie belanglose Felder rotieren.

​

Ergebnisse mit Webhooks verfolgen

• subscription.active: Mandat autorisiert und Abonnement aktiviert
• subscription.failed: Erstellung fehlgeschlagen (z. B. Mandatsfehler)
• subscription.on_hold: Abonnement auf Hold gesetzt (z. B. unbezahlter Zustand)
• payment.succeeded: Zahlung erfolgreich
• payment.failed: Zahlung fehlgeschlagen

​

Testen und nächste Schritte

​

Fehlersuche

• 422 Invalid Request: Stellen Sie sicher, dass on_demand.mandate_only bei der Erstellung und product_price bei Belastungen bereitgestellt wird.
• Währungsfehler: Wenn Sie product_currency überschreiben, bestätigen Sie, dass diese Währung für Ihr Konto und Ihren Kunden unterstützt wird.
• Keine empfangenen Webhooks: Überprüfen Sie Ihre Webhook-URL und die Konfiguration des Signatur-Geheimnisses.