On-Demand-Abonnements

​

Übersicht

• Ein On-Demand-Abonnement zu erstellen (ein Mandat mit optionalem Anfangspreis zu autorisieren)
• Nachfolgende Gebühren 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

​

Wie On-Demand funktioniert

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 Gebühren für dieses Abonnement mit benutzerdefinierten Beträgen über den speziellen Gebührenendpunkt.
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.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": []
}

​

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

​

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); 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 Ihr eigenes Wiederholungssystem pflegen, unterscheiden Sie Wiederholungen über Metadaten (z. B. retry_attempt).

​

Vorgeschlagener Wiederholungszeitplan (Abonnements)

• 1. Versuch: Sofort, wenn Sie die Gebühr 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 Burst-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 Tageszeit-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/Queue, der präzise Zeitstempel speichert; berechnen Sie den nächsten Versuch zum genauen Tageszeitversatz (z. B. T + 3 days zur gleichen HH:MM).
• Behalten Sie den letzten erfolgreichen Zahlungszeitstempel T bei und beziehen Sie ihn ein, 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, Betrugs-/Risikosysteme zu „umgehen“, indem Sie unwesentliche Felder rotieren.

​

Ergebnisse mit Webhooks verfolgen

• subscription.active: Mandat genehmigt und Abonnement aktiviert
• subscription.failed: Erstellung fehlgeschlagen (z. B. Mandatsfehler)
• subscription.on_hold: Abonnement auf Hold gesetzt (z. B. unbezahlter Zustand)
• payment.succeeded: Gebühr erfolgreich
• payment.failed: Gebühr 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 Gebühren 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.