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 Anfangsgebühr zu erheben.
2. Später erstellen Sie Zahlungen gegen dieses Abonnement mit benutzerdefinierten Beträgen über den speziellen Zahlungsendpunkt.
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 den Wiederholungen.
• Wiederholungsgrenzen: Begrenzen Sie die Gesamtzahl der Wiederholungen (maximal 3–4 Versuche).
• Intelligente Filterung: Wiederholen Sie nur bei wiederholbaren Fehlern (z. B. Netzwerk-/Ausstellerfehler, unzureichende Mittel); niemals bei harten Ablehnungen wiederholen.
• 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 Ihr eigenes Wiederholungssystem 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 an dem ursprünglichen Autorisierungszeitstempel, um “Burst”-Verhalten in Ihrem Portfolio zu vermeiden.
• Beispiel: Wenn der Kunde um 13:10 Uhr heute einen Test oder ein Mandat startet, planen Sie nachfolgende Wiederholungen um 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 die letzte erfolgreiche Zahlungszeit T speichern, planen Sie den nächsten Versuch um T + X days, um die zeitliche Ausrichtung zu bewahren.

​

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/Warteschlange, der präzise Zeitstempel speichert; berechnen Sie den nächsten Versuch zum genauen Zeitversatz (z. B. T + 3 days zur gleichen HH:MM).
• Behalten Sie den letzten erfolgreichen Zahlungszeitstempel T bei, um den nächsten Versuch zu berechnen; bündeln Sie niemals mehrere Abonnements zur gleichen Zeit.
• Bewerten Sie immer den letzten Ablehnungsgrund; stoppen Sie Wiederholungen bei harten Ablehnungen in der obigen Ausnahmeliste.
• Begrenzen Sie gleichzeitige Wiederholungen pro Kunde und pro Konto, um versehentliche Spitzen zu vermeiden.
• Kommunizieren Sie proaktiv: E-Mail/SMS an den Kunden, um seine Zahlungsmethode vor dem nächsten geplanten Versuch zu aktualisieren.
• Verwenden Sie Metadaten nur zur Beobachtbarkeit (z. B. retry_attempt); versuchen Sie niemals, die Betrugs-/Risikosysteme durch das Rotieren unwesentlicher Felder zu “umgehen”.

​

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 Ungültige Anfrage: Stellen Sie sicher, dass on_demand.mandate_only bei der Erstellung angegeben ist und product_price für Zahlungen angegeben ist.
• Währungsfehler: Wenn Sie product_currency überschreiben, bestätigen Sie, dass es für Ihr Konto und Ihren Kunden unterstützt wird.
• Keine Webhooks empfangen: Überprüfen Sie Ihre Webhook-URL und die Konfiguration des Signaturgeheimnisses.