Skip to main content
Das C# SDK bietet .NET-Anwendungen typisierten Zugriff auf die Dodo Payments REST API. Jede API-Methode ist asynchron und gibt einen Task zurück, Anforderungen und Antworten sind typisierte Klassen, und der Client wiederholt fehlgeschlagene Anforderungen automatisch.

Installation

Install the package from NuGet:
Das SDK erfordert .NET Standard 2.0 oder höher und wird außerdem mit einem .NET 8-Build ausgeliefert. Es funktioniert mit ASP.NET Core, Konsolenanwendungen und anderen .NET-Projekttypen. Die Beispiele auf dieser Seite verwenden die C#-12-Syntax, etwa Collection Expressions.

Quick Start

Erstellen Sie einen Client und anschließend eine Checkout-Sitzung:
Wenn Sie BearerToken nicht festlegen, liest der Client die Umgebungsvariable DODO_PAYMENTS_API_KEY. Wenn Sie weder BaseUrl noch DODO_PAYMENTS_BASE_URL festlegen, verbindet sich der Client mit dem Live-Modus. Informationen zur Verwendung des Testmodus finden Sie unter Umgebungen. Ein API-Schlüssel für den Testmodus funktioniert nur im Testmodus.
Bewahren Sie API-Schlüssel in Umgebungsvariablen, User Secrets oder Azure Key Vault auf. Hardcodieren Sie sie niemals in Ihrem Quellcode und committen Sie sie niemals in die Versionsverwaltung.

Kernfunktionen

Async/Await

Jede API-Methode gibt einen Task zurück und akzeptiert einen optionalen CancellationToken.

Strong Typing

Typisierte Anforderungs- und Antwortklassen mit Annotationen für nullable Referenztypen.

Smart Retries

Standardmäßig zwei Wiederholungsversuche mit exponentiellem Backoff bei Verbindungsfehlern und wiederholbaren Statuscodes.

Error Handling

Eine Exception-Klasse für jeden gängigen HTTP-Fehlerstatus mit dem Statuscode und dem Antworttext.

Konfiguration

Umgebungsvariablen

Speichern Sie Ihren API-Schlüssel in einer Umgebungsvariablen:
.env
Ein mit new() erstellter Client liest seine Einstellungen aus der Umgebung:
Der Client liest diese Umgebungsvariablen, wenn Sie die entsprechende Eigenschaft nicht festlegen: Wenn weder BearerToken noch DODO_PAYMENTS_API_KEY festgelegt ist, löst der Client DodoPaymentsInvalidDataException aus. WebhookKey enthält Ihr Webhook-Signaturgeheimnis. Das C# SDK verfügt jedoch über keine Methode zur Überprüfung von Webhook-Signaturen. Folgen Sie zur Überprüfung Webhooks.

Manuelle Konfiguration

Legen Sie Eigenschaften auf dem Client fest, um die Umgebungsvariablen zu überschreiben:

Umgebungen

Der Client verbindet sich standardmäßig mit dem Live-Modus (https://live.dodopayments.com). Um den Testmodus (https://test.dodopayments.com) zu verwenden, setzen Sie BaseUrl auf EnvironmentUrl.TestMode:

Wiederholungsversuche

Das SDK wiederholt Verbindungsfehler und Antworten mit dem Status 408, 409, 429 oder 500 und höher. Standardmäßig wird die Anfrage zweimal mit exponentiellem Backoff wiederholt. Setzen Sie MaxRetries, um die Anzahl der Wiederholungsversuche zu ändern, oder setzen Sie es auf 0, um Wiederholungsversuche zu deaktivieren:

Timeouts

Jeder Anfrageversuch läuft standardmäßig nach 1 Minute ab. Das Timeout umfasst keine Wiederholungsversuche. Setzen Sie Timeout, um diesen Wert zu ändern:

Überschreibungen pro Anfrage

Um Einstellungen für einen einzelnen Aufruf zu ändern, rufen Sie WithOptions auf dem Client oder einem Service auf. Die Methode gibt eine modifizierte Kopie zurück, die denselben Verbindungspool verwendet. Der ursprüngliche Client bleibt unverändert:

Häufige Vorgänge

Die Beispiele in diesem Abschnitt verwenden den client aus dem Schnellstart.

Checkout-Sitzung erstellen

Erstellen Sie eine Checkout-Sitzung und leiten Sie den Kunden anschließend zur zurückgegebenen CheckoutUrl weiter:
Jede Checkout-URL kann einmal verwendet werden und läuft nach 24 Stunden ab. Eine Übersicht über alle Sitzungsoptionen finden Sie unter Checkout-Sitzungen.

Kunden verwalten

Erstellen Sie einen Kunden mit einer E-Mail-Adresse und einem Namen und rufen Sie ihn anschließend über seine ID ab:
Customers.Retrieve akzeptiert die ID auch als String, zum Beispiel client.Customers.Retrieve("cus_123").

Abonnements verwalten

Erstellen Sie ein Abonnement und belasten Sie es anschließend, wenn es sich um ein On-Demand-Abonnement handelt.
POST /subscriptions (die Subscriptions.Create-Methode des SDK) ist veraltet. Sie funktioniert weiterhin für bestehende Integrationen. Neue Integrationen sollten Abonnements jedoch über eine Checkout-Sitzung erstellen.
Billing erfordert nur Country, einen zweistelligen ISO-Ländercode. Customer akzeptiert ein AttachExistingCustomer, um einen bestehenden Kunden zu verknüpfen, oder ein NewCustomer, um einen Kunden zu erstellen. Charge ist für On-Demand-Abonnements vorgesehen, und ProductPrice wird in der kleinsten Währungseinheit angegeben.

Fehlerbehandlung

Wenn die API einen Fehlerstatus zurückgibt, löst das SDK eine Unterklasse von DodoPaymentsApiException aus, die über die Eigenschaften StatusCode und ResponseBody verfügt. Die Exception-Klasse hängt vom Statuscode ab. Alle 4xx-Exceptions erben von DodoPayments4xxException. Ein 4xx-Status ohne eigene Klasse, etwa 409, löst DodoPayments4xxException aus. DodoPaymentsUnexpectedStatusCodeException deckt Status außerhalb der 4xx- und 5xx-Bereiche ab. Das SDK löst außerdem folgende Exceptions aus:
  • DodoPaymentsIOException: Ein I/O- oder Netzwerkfehler.
  • DodoPaymentsInvalidDataException: Das SDK konnte die Antwortdaten nicht interpretieren, beispielsweise weil eine erforderliche Eigenschaft fehlt.
  • DodoPaymentsException: Die Basisklasse jeder SDK-Exception.

Paginierung

Listenmethoden geben eine Ergebnisseite zurück. Sie können jedes Element durchlaufen oder die Seiten selbst durchgehen.

Automatische Paginierung

Paginate gibt einen IAsyncEnumerable zurück, der bei Bedarf die nächste Seite abruft:

Manuelle Paginierung

Um jeweils mit einer Seite zu arbeiten, lesen Sie Items und rufen Sie anschließend HasNext() und Next() auf:
Um die Seitengröße festzulegen, übergeben Sie ein PaymentListParams aus dem Namespace DodoPayments.Client.Models.Payments, zum Beispiel client.Payments.List(new PaymentListParams { PageSize = 50 }).

ASP.NET-Core-Integration

Registrieren Sie einen Client als Singleton im Dependency-Injection-Container und lesen Sie den API-Schlüssel aus der Konfiguration:
Program.cs
Fügen Sie den Schlüssel Ihrer Konfiguration hinzu, zum Beispiel in appsettings.json:
appsettings.json
Speichern Sie den Schlüssel in der Entwicklung mithilfe von User Secrets statt in appsettings.json:

Ressourcen

NuGet Package

Paketversionen und Installationsbefehle.

GitHub Repository

Quellcode, Releases und Beispiele.

API Reference

Jeder Endpunkt, jeder Parameter und jede Antwort.

Discord Community

Stellen Sie Fragen und tauschen Sie sich mit anderen Entwicklern aus.

Support

Hilfe zum C# SDK:
Zuletzt geändert am 26. September 2026