Java

Das Java SDK ermöglicht Java-Anwendungen typisierten Zugriff auf die REST API von Dodo Payments. Es verwendet durchgehend Java-Typen: Optional für Felder, die fehlen können, Stream zum Durchlaufen von Ergebnissen und CompletableFuture für asynchrone Aufrufe.

Installation

Maven

Fügen Sie die Abhängigkeit zu Ihrer pom.xml hinzu:

pom.xml

<dependency>
  <groupId>com.dodopayments.api</groupId>
  <artifactId>dodo-payments-java</artifactId>
  <version>1.118.0</version>
</dependency>

Gradle

Fügen Sie die Abhängigkeit zu Ihrem build.gradle.kts hinzu:

build.gradle.kts

implementation("com.dodopayments.api:dodo-payments-java:1.118.0")

SDK-Releases fügen Unterstützung für API-Änderungen hinzu. Um die neueste Version zu finden, prüfen Sie Maven Central.

Das SDK erfordert Java 8 oder höher und läuft daher auch unter Java 11, 17 und 21.

Schnellstart

Erstellen Sie einen Client und anschließend eine Checkout-Sitzung:

import com.dodopayments.api.client.DodoPaymentsClient;
import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient;
import com.dodopayments.api.models.checkoutsessions.CheckoutSessionRequest;
import com.dodopayments.api.models.checkoutsessions.CheckoutSessionResponse;
import com.dodopayments.api.models.checkoutsessions.ProductItemReq;

// Configure using environment variables (DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_WEBHOOK_KEY, DODO_PAYMENTS_BASE_URL)
// Or system properties (dodopayments.apiKey, dodopayments.webhookKey, dodopayments.baseUrl)
DodoPaymentsClient client = DodoPaymentsOkHttpClient.fromEnv();

CheckoutSessionRequest params = CheckoutSessionRequest.builder()
    .addProductCart(ProductItemReq.builder()
        .productId("pdt_123")
        .quantity(1)
        .build())
    .build();
    
CheckoutSessionResponse checkoutSessionResponse = client.checkoutSessions().create(params);
System.out.println(checkoutSessionResponse.sessionId());

fromEnv() stellt die Verbindung standardmäßig mit dem Live-Modus her, sofern DODO_PAYMENTS_BASE_URL oder dodopayments.baseUrl nichts anderes festlegt. Informationen zur Verwendung des Testmodus finden Sie unter Testmodus. Ein API-Schlüssel für den Testmodus funktioniert nur im Testmodus.

Bewahren Sie API-Schlüssel in Umgebungsvariablen, Systemeigenschaften oder einem Secrets Manager auf. Hardcodieren Sie sie niemals in Ihrem Quellcode.

Kernfunktionen

Type Safety

Typisierte Request- und Response-Klassen für Prüfungen zur Compile-Zeit.

Shared Client

Erstellen Sie einen Client und verwenden Sie ihn für mehrere Requests wieder: Er verwaltet die Verbindung sowie die Thread-Pools. Request- und Response-Objekte sind unveränderlich.

Builder Pattern

Jede Request-Klasse verfügt über einen Builder, und toBuilder() erstellt eine modifizierte Kopie.

Async Support

client.async() gibt einen Client zurück, dessen Methoden CompletableFuture zurückgeben.

Konfiguration

Umgebungsvariablen

fromEnv() liest diese Umgebungsvariablen oder die entsprechenden Systemeigenschaften. Systemeigenschaften haben Vorrang:

.env

DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_BASE_URL=https://live.dodopayments.com

// Automatically reads from environment variables
DodoPaymentsClient client = DodoPaymentsOkHttpClient.fromEnv();

Der API-Schlüssel stammt aus DODO_PAYMENTS_API_KEY oder dodopayments.apiKey. Das Webhook-Signaturgeheimnis stammt aus DODO_PAYMENTS_WEBHOOK_KEY oder dodopayments.webhookKey und die Basis-URL aus DODO_PAYMENTS_BASE_URL oder dodopayments.baseUrl. Erstellen Sie einen Client und verwenden Sie ihn wieder, da jeder Client über einen eigenen Verbindungs- und Thread-Pool verfügt. Um einen Webhook zu verifizieren, übergeben Sie den unveränderten Request-Body und die Header an client.webhooks().unwrap(UnwrapWebhookParams.builder().body(rawBody).headers(headers).build()), wobei headers ein com.dodopayments.api.core.http.Headers ist. Die Methode prüft die Signatur mit Ihrem Webhook-Schlüssel und gibt das geparste Event zurück oder löst DodoPaymentsWebhookException aus. Ohne Header verifiziert unwrap die Signatur nicht. client.webhooks().unsafeUnwrap(rawBody) parst den Body, ohne ihn zu verifizieren; verwenden Sie die Methode daher nur zum Testen. Siehe Webhooks.

Manuelle Konfiguration

Legen Sie jede Option im Builder fest:

import java.time.Duration;

DodoPaymentsClient client = DodoPaymentsOkHttpClient.builder()
    .bearerToken("your_api_key_here")
    .baseUrl("https://live.dodopayments.com")
    .maxRetries(4)
    .timeout(Duration.ofSeconds(30))
    .responseValidation(true)
    .build();

Standardmäßig führt der Client zwei Wiederholungsversuche durch und bricht nach 1 Minute mit einem Timeout ab. Er wiederholt Requests bei Verbindungsfehlern und bei Responses mit dem Status 408, 409, 429 oder 500 und höher. Um das Timeout für einen einzelnen Aufruf zu überschreiben, übergeben Sie RequestOptions.builder().timeout(Duration.ofSeconds(30)).build() als zweites Argument der Methode. responseValidation(true) prüft vorab, ob die gesamte Response den erwarteten Typen entspricht. Ohne diese Option löst das SDK DodoPaymentsInvalidDataException erst aus, wenn Sie eine Eigenschaft mit einem unerwarteten Typ lesen.

Testmodus

Um den Testmodus (https://test.dodopayments.com) zu verwenden, rufen Sie testMode() im Builder auf:

DodoPaymentsClient testClient = DodoPaymentsOkHttpClient.builder()
    .fromEnv()
    .testMode()
    .build();

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 an die zurückgegebene Checkout-URL weiter:

CheckoutSessionRequest params = CheckoutSessionRequest.builder()
    .addProductCart(ProductItemReq.builder()
        .productId("pdt_123")
        .quantity(1)
        .build())
    .returnUrl("https://yourdomain.com/return")
    .build();

CheckoutSessionResponse session = client.checkoutSessions().create(params);
System.out.println("Checkout URL: " + session.checkoutUrl().orElse(""));

checkoutUrl() gibt ein Optional<String> zurück. 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 E-Mail-Adresse, Namen und Metadaten und rufen Sie ihn anschließend über seine ID ab:

import com.dodopayments.api.core.JsonValue;
import com.dodopayments.api.models.customers.Customer;
import com.dodopayments.api.models.customers.CustomerCreateParams;
import com.dodopayments.api.models.misc.Metadata;

// Create a customer
CustomerCreateParams createParams = CustomerCreateParams.builder()
    .email("customer@example.com")
    .name("John Doe")
    .metadata(Metadata.builder()
        .putAdditionalProperty("user_id", JsonValue.from("12345"))
        .build())
    .build();

Customer customer = client.customers().create(createParams);

// Retrieve customer
Customer retrieved = client.customers().retrieve("cus_123");
System.out.println("Customer: " + retrieved.name() + " (" + retrieved.email() + ")");

Abonnements verwalten

Erstellen Sie ein Abonnement mit einem Zahlungslink 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.

import com.dodopayments.api.models.payments.AttachExistingCustomer;
import com.dodopayments.api.models.payments.BillingAddress;
import com.dodopayments.api.models.misc.CountryCode;
import com.dodopayments.api.models.subscriptions.SubscriptionChargeParams;
import com.dodopayments.api.models.subscriptions.SubscriptionChargeResponse;
import com.dodopayments.api.models.subscriptions.SubscriptionCreateParams;
import com.dodopayments.api.models.subscriptions.SubscriptionCreateResponse;

// Create a subscription
SubscriptionCreateParams subscriptionParams = SubscriptionCreateParams.builder()
    .billing(BillingAddress.builder()
        .city("San Francisco")
        .country(CountryCode.US)
        .state("CA")
        .street("1 Market St")
        .zipcode("94105")
        .build())
    .customer(AttachExistingCustomer.builder()
        .customerId("cus_123")
        .build())
    .productId("pdt_456")
    .quantity(1)
    .paymentLink(true)
    .returnUrl("https://yourdomain.com/return")
    .build();

SubscriptionCreateResponse subscription = client.subscriptions().create(subscriptionParams);
System.out.println("Subscription ID: " + subscription.subscriptionId());

// Charge an on-demand subscription
// product_price is in the lowest currency denomination (e.g., 2500 = $25.00 USD)
SubscriptionChargeParams chargeParams = SubscriptionChargeParams.builder()
    .subscriptionId(subscription.subscriptionId())
    .productPrice(2500)
    .build();

SubscriptionChargeResponse chargeResponse = client.subscriptions().charge(chargeParams);
System.out.println("Payment ID: " + chargeResponse.paymentId());

productPrice wird in der kleinsten Währungseinheit angegeben, etwa Cent für USD oder Paise für INR. Um 25,00 $ zu berechnen, übergeben Sie 2500.

subscriptions().charge(...) ist für On-Demand-Abonnements vorgesehen. Dodo Payments stellt andere Abonnements automatisch nach dem Abrechnungszeitplan des Produkts in Rechnung.

Nutzungsbasierte Abrechnung

Meters konfigurieren

Erstellen Sie einen Meter, der Events zählt, und listen Sie anschließend Ihre Meters auf. autoPager() durchläuft jeden Meter und ruft bei Bedarf weitere Seiten ab:

import com.dodopayments.api.models.meters.*;

// Create API calls meter
MeterCreateParams apiMeterParams = MeterCreateParams.builder()
    .name("API Requests")
    .eventName("api_request")
    .aggregation(MeterAggregation.builder()
        .type(MeterAggregation.Type.COUNT)
        .build())
    .measurementUnit("calls")
    .build();

Meter apiMeter = client.meters().create(apiMeterParams);
System.out.println("Meter created: " + apiMeter.id());

// List all meters
client.meters().list()
    .autoPager()
    .forEach(m -> System.out.println("Meter: " + m.name() + " - " + m.aggregation()));

Nutzungsereignisse aufnehmen

Senden Sie ein Nutzungsereignis für einen Kunden. Die Werte der Event-Metadaten sind JsonValue-Objekte:

import com.dodopayments.api.core.JsonValue;
import com.dodopayments.api.models.usageevents.EventInput;
import com.dodopayments.api.models.usageevents.*;
import java.time.OffsetDateTime;

// Ingest single event
UsageEventIngestParams singleEventParams = UsageEventIngestParams.builder()
    .addEvent(EventInput.builder()
        .eventId("api_call_" + System.currentTimeMillis())
        .customerId("cus_abc123")
        .eventName("api_request")
        .timestamp(OffsetDateTime.now())
        .metadata(EventInput.Metadata.builder()
            .putAdditionalProperty("endpoint", JsonValue.from("/api/v1/users"))
            .putAdditionalProperty("method", JsonValue.from("GET"))
            .putAdditionalProperty("tokens_used", JsonValue.from("150"))
            .build())
        .build())
    .build();

UsageEventIngestResponse response = client.usageEvents().ingest(singleEventParams);
System.out.println("Processed: " + response.ingestedCount());

eventId ist der Idempotency-Key. Verwenden Sie daher für jedes Event einen eindeutigen Wert. Ein timestamp, das mehr als 1 Stunde in der Vergangenheit oder mehr als 5 Minuten in der Zukunft liegt, wird abgelehnt.

Events stapelweise aufnehmen

Senden Sie bis zu 1.000 Events in einem Request. Dieses Beispiel verwendet die Imports aus dem vorherigen Beispiel:

UsageEventIngestParams.Builder batchBuilder = UsageEventIngestParams.builder();

for (int i = 0; i < 100; i++) {
    batchBuilder.addEvent(EventInput.builder()
        .eventId("batch_event_" + i + "_" + System.currentTimeMillis())
        .customerId("cus_abc123")
        .eventName("video_transcode")
        .timestamp(OffsetDateTime.now().minusSeconds(i))
        .metadata(EventInput.Metadata.builder()
            .putAdditionalProperty("video_id", JsonValue.from("video_" + i))
            .putAdditionalProperty("duration_seconds", JsonValue.from(String.valueOf(120 + i)))
            .build())
        .build());
}

UsageEventIngestResponse batchResponse = client.usageEvents().ingest(batchBuilder.build());
System.out.println("Batch processed: " + batchResponse.ingestedCount() + " events");

Fehlerbehandlung

Das SDK löst ungeprüfte Exceptions aus. Bei einem Fehlerstatus löst es eine Unterklasse von DodoPaymentsServiceException aus, die über statusCode(), headers() und body() verfügt. Fangen Sie die spezifischen Klassen, die Sie behandeln möchten, vor der Basisklasse ab:

import com.dodopayments.api.errors.*;
import com.dodopayments.api.models.payments.Payment;

try {
    Payment payment = client.payments().retrieve("pay_invalid");
} catch (NotFoundException e) {
    System.err.println("Payment not found: " + e.getMessage());
} catch (UnauthorizedException e) {
    System.err.println("Authentication failed: " + e.getMessage());
} catch (PermissionDeniedException e) {
    System.err.println("Permission denied: " + e.getMessage());
} catch (BadRequestException e) {
    System.err.println("Invalid request: " + e.getMessage());
} catch (UnprocessableEntityException e) {
    System.err.println("Validation error: " + e.getMessage());
} catch (RateLimitException e) {
    System.err.println("Rate limit exceeded: " + e.getMessage());
    // Thrown after the SDK's automatic retries are used up
} catch (InternalServerException e) {
    System.err.println("Server error: " + e.getMessage());
} catch (DodoPaymentsServiceException e) {
    System.err.println("API error: " + e.statusCode() + " - " + e.getMessage());
}

Statuscodes ohne eigene Klasse, etwa 409, lösen UnexpectedStatusCodeException aus. Netzwerkfehler lösen DodoPaymentsIoException aus, und Responses, die das SDK nicht interpretieren kann, lösen DodoPaymentsInvalidDataException aus. Alle diese Klassen erweitern DodoPaymentsException.

Das SDK wiederholt Requests bei Verbindungsfehlern und bei Responses mit dem Status 408, 409, 429 oder 500 und höher standardmäßig zweimal mit exponentiellem Backoff.

Asynchrone Vorgänge

Rufen Sie async() auf dem Client auf, um einen asynchronen Client abzurufen. Seine Methoden geben ein CompletableFuture zurück:

import java.util.concurrent.CompletableFuture;

CompletableFuture<CheckoutSessionResponse> future = client.async()
    .checkoutSessions()
    .create(params);

// Handle response asynchronously
future.thenAccept(response -> {
    System.out.println("Session created: " + response.sessionId());
}).exceptionally(ex -> {
    System.err.println("Error: " + ex.getMessage());
    return null;
});

Um von Anfang an einen asynchronen Client zu erstellen, verwenden Sie DodoPaymentsOkHttpClientAsync.fromEnv().

Spring-Boot-Integration

Konfigurationsklasse

Registrieren Sie einen Client als Bean und wählen Sie die Umgebung über eine Property aus:

import com.dodopayments.api.client.DodoPaymentsClient;
import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class DodoPaymentsConfig {
    
    @Value("${dodo.api.key}")
    private String apiKey;
    
    @Value("${dodo.environment:test}")
    private String environment;
    
    @Bean
    public DodoPaymentsClient dodoPayments() {
        return DodoPaymentsOkHttpClient.builder()
            .bearerToken(apiKey)
            .baseUrl(environment.equals("live") 
                ? "https://live.dodopayments.com" 
                : "https://test.dodopayments.com")
            .build();
    }
}

Service-Schicht

Injizieren Sie den Client in einen Service:

import com.dodopayments.api.client.DodoPaymentsClient;
import com.dodopayments.api.models.checkoutsessions.*;
import java.util.List;
import org.springframework.stereotype.Service;

@Service
public class PaymentService {
    
    private final DodoPaymentsClient client;
    
    public PaymentService(DodoPaymentsClient client) {
        this.client = client;
    }
    
    public CheckoutSessionResponse createCheckout(List<ProductItemReq> items) {
        CheckoutSessionRequest params = CheckoutSessionRequest.builder()
            .productCart(items)
            .returnUrl("https://yourdomain.com/return")
            .build();
            
        return client.checkoutSessions().create(params);
    }
}

Ressourcen

GitHub Repository

Quellcode, Releases und die vollständige Methodenliste.

API Reference

Jeder Endpoint, Parameter und jede Response.

Discord Community

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

Report Issues

Melden Sie Fehler oder schlagen Sie Funktionen vor.

Support

Hilfe zum Java SDK:

Discord: Treten Sie dem Community-Server bei, um Hilfe in Echtzeit zu erhalten.
E-Mail: Kontaktieren Sie support@dodopayments.com.
GitHub: Erstellen Sie ein Issue im Repository.

Mitwirken

Wenn Sie mitwirken möchten, lesen Sie die Richtlinien für Mitwirkende.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Installation

Maven

Gradle

Schnellstart

Kernfunktionen

Type Safety

Shared Client

Builder Pattern

Async Support

Konfiguration

Umgebungsvariablen

Manuelle Konfiguration

Testmodus

Häufige Vorgänge

Checkout-Sitzung erstellen

Kunden verwalten

Abonnements verwalten

Nutzungsbasierte Abrechnung

Meters konfigurieren

Nutzungsereignisse aufnehmen

Events stapelweise aufnehmen

Fehlerbehandlung

Asynchrone Vorgänge

Spring-Boot-Integration

Konfigurationsklasse

Service-Schicht

Ressourcen

GitHub Repository

API Reference

Discord Community

Report Issues

Support

Mitwirken

​Installation

​Maven

​Gradle

​Schnellstart

​Kernfunktionen

Type Safety

Shared Client

Builder Pattern

Async Support

​Konfiguration

​Umgebungsvariablen

​Manuelle Konfiguration

​Testmodus

​Häufige Vorgänge

​Checkout-Sitzung erstellen

​Kunden verwalten

​Abonnements verwalten

​Nutzungsbasierte Abrechnung

​Meters konfigurieren

​Nutzungsereignisse aufnehmen

​Events stapelweise aufnehmen

​Fehlerbehandlung

​Asynchrone Vorgänge

​Spring-Boot-Integration

​Konfigurationsklasse

​Service-Schicht

​Ressourcen

GitHub Repository

API Reference

Discord Community

Report Issues

​Support

​Mitwirken

Installation

Maven

Gradle

Schnellstart

Kernfunktionen

Konfiguration

Umgebungsvariablen

Manuelle Konfiguration

Testmodus

Häufige Vorgänge

Checkout-Sitzung erstellen

Kunden verwalten

Abonnements verwalten

Nutzungsbasierte Abrechnung

Meters konfigurieren

Nutzungsereignisse aufnehmen

Events stapelweise aufnehmen

Fehlerbehandlung

Asynchrone Vorgänge

Spring-Boot-Integration

Konfigurationsklasse

Service-Schicht

Ressourcen

Support

Mitwirken