Java

Le SDK Java fournit aux applications Java un accès typé à l’API REST Dodo Payments. Il utilise des types Java partout : Optional pour les champs qui peuvent être absents, Stream pour parcourir les résultats et CompletableFuture pour les appels asynchrones.

Installation

Maven

Ajoutez la dépendance dans votre pom.xml :

pom.xml

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

Gradle

Ajoutez la dépendance à votre build.gradle.kts :

build.gradle.kts

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

Les versions du SDK prennent en charge les modifications de l’API. Pour trouver la version la plus récente, consultez Maven Central.

Le SDK nécessite Java 8 ou une version ultérieure ; il fonctionne donc également avec Java 11, 17 et 21.

Démarrage rapide

Créez un client, puis créez une session de checkout :

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() se connecte au mode live, sauf si DODO_PAYMENTS_BASE_URL ou dodopayments.baseUrl indique le contraire. Pour utiliser le mode test, consultez Mode test. Une clé API du mode test fonctionne uniquement dans le mode test.

Conservez les clés API dans des variables d’environnement, des propriétés système ou un gestionnaire de secrets. Ne les codez jamais en dur dans votre code source.

Fonctionnalités principales

Type Safety

Classes de requête et de réponse typées pour effectuer des vérifications à la compilation.

Shared Client

Créez un client et réutilisez-le pour toutes les requêtes : il conserve les pools de connexions et de threads. Les objets de requête et de réponse sont immuables.

Builder Pattern

Chaque classe de requête possède un builder, et toBuilder() crée une copie modifiée.

Async Support

client.async() renvoie un client dont les méthodes renvoient CompletableFuture.

Configuration

Variables d’environnement

fromEnv() lit ces variables d’environnement ou les propriétés système correspondantes. Les propriétés système sont prioritaires :

.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();

La clé API provient de DODO_PAYMENTS_API_KEY ou dodopayments.apiKey. Le secret de signature du webhook provient de DODO_PAYMENTS_WEBHOOK_KEY ou dodopayments.webhookKey, et l’URL de base de DODO_PAYMENTS_BASE_URL ou dodopayments.baseUrl. Créez un client et réutilisez-le, car chaque client possède son propre pool de connexions et ses propres pools de threads. Pour vérifier un webhook, transmettez le corps brut de la requête et les en-têtes à client.webhooks().unwrap(UnwrapWebhookParams.builder().body(rawBody).headers(headers).build()), où headers est un com.dodopayments.api.core.http.Headers. Cette méthode vérifie la signature avec votre clé de webhook et renvoie l’événement analysé, ou lève DodoPaymentsWebhookException. Sans en-têtes, unwrap ne vérifie pas la signature. client.webhooks().unsafeUnwrap(rawBody) analyse le corps sans le vérifier ; utilisez-le donc uniquement pour les tests. Consultez Webhooks.

Configuration manuelle

Définissez chaque option sur le builder :

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();

Par défaut, le client effectue deux nouvelles tentatives et expire après 1 minute. Il réessaie en cas d’erreurs de connexion et pour les réponses présentant le statut 408, 409, 429 ou 500 et plus. Pour remplacer le délai d’expiration d’un seul appel, transmettez RequestOptions.builder().timeout(Duration.ofSeconds(30)).build() comme deuxième argument de la méthode. responseValidation(true) vérifie dès le départ que l’intégralité de la réponse correspond aux types attendus. Sans cette option, le SDK lève DodoPaymentsInvalidDataException uniquement lorsque vous lisez une propriété dont le type est inattendu.

Mode test

Pour utiliser le mode test (https://test.dodopayments.com), appelez testMode() sur le builder :

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

Opérations courantes

Les exemples de cette section utilisent le client de la section Démarrage rapide.

Créer une session de checkout

Créez une session de checkout, puis redirigez le client vers l’URL de checkout renvoyée :

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() renvoie un Optional<String>. Chaque URL de checkout fonctionne une seule fois et expire après 24 heures. Pour connaître toutes les options de session, consultez Sessions de checkout.

Gérer les clients

Créez un client avec une adresse e-mail, un nom et des métadonnées, puis récupérez-le par son ID :

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() + ")");

Gérer les abonnements

Créez un abonnement avec un lien de paiement, puis facturez-le s’il s’agit d’un abonnement à la demande.

POST /subscriptions (la méthode subscriptions().create() du SDK) est obsolète. Elle fonctionne toujours pour les intégrations existantes, mais les nouvelles intégrations doivent créer des abonnements via une session de checkout.

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 est exprimé dans la plus petite unité monétaire, comme les centimes pour l’USD ou les paise pour l’INR. Pour facturer $25.00, transmettez 2500.

subscriptions().charge(...) est destiné aux abonnements à la demande. Dodo Payments facture automatiquement les autres abonnements selon le calendrier de facturation du produit.

Facturation basée sur l’utilisation

Configurer les compteurs

Créez un compteur qui dénombre les événements, puis répertoriez vos compteurs. autoPager() parcourt chaque compteur et récupère d’autres pages si nécessaire :

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()));

Ingérer des événements d’utilisation

Envoyez un événement d’utilisation pour un client. Les valeurs des métadonnées d’événement sont des objets JsonValue :

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 est la clé d’idempotence ; attribuez donc une valeur unique à chaque événement. Un timestamp datant de plus d’une heure ou situé à plus de 5 minutes dans le futur est rejeté.

Ingérer des événements par lots

Envoyez jusqu’à 1 000 événements dans une seule requête. Cet exemple utilise les imports de l’exemple précédent :

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");

Gestion des erreurs

Le SDK lève des exceptions non vérifiées. En cas de statut d’erreur, il lève une sous-classe de DodoPaymentsServiceException, qui possède statusCode(), headers() et body(). Interceptez les classes spécifiques que vous souhaitez gérer avant la classe de base :

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());
}

Les statuts qui ne possèdent pas leur propre classe, comme 409, lèvent UnexpectedStatusCodeException. Les défaillances réseau lèvent DodoPaymentsIoException, et les réponses que le SDK ne peut pas interpréter lèvent DodoPaymentsInvalidDataException. Toutes ces exceptions étendent DodoPaymentsException.

Le SDK réessaie en cas d’erreurs de connexion et pour les réponses présentant le statut 408, 409, 429 ou 500 et plus, deux fois par défaut, avec un délai d’attente exponentiel.

Opérations asynchrones

Appelez async() sur le client pour obtenir un client asynchrone. Ses méthodes renvoient un CompletableFuture :

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;
});

Pour créer directement un client asynchrone, utilisez DodoPaymentsOkHttpClientAsync.fromEnv().

Intégration Spring Boot

Classe de configuration

Enregistrez un client comme bean et choisissez l’environnement à partir d’une propriété :

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();
    }
}

Couche de service

Injectez le client dans un 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);
    }
}

Ressources

GitHub Repository

Code source, versions et liste complète des méthodes.

API Reference

Chaque endpoint, paramètre et réponse.

Discord Community

Posez vos questions et échangez avec d’autres développeurs.

Report Issues

Signalez des bugs ou demandez des fonctionnalités.

Assistance

Pour obtenir de l’aide concernant le SDK Java :

Discord : Rejoignez le serveur communautaire pour obtenir de l’aide en temps réel.
E-mail : Contactez support@dodopayments.com.
GitHub : Ouvrez une issue sur le dépôt.

Contribuer

Pour contribuer, consultez les directives de contribution.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Installation

Maven

Gradle

Démarrage rapide

Fonctionnalités principales

Type Safety

Shared Client

Builder Pattern

Async Support

Configuration

Variables d’environnement

Configuration manuelle

Mode test

Opérations courantes

Créer une session de checkout

Gérer les clients

Gérer les abonnements

Facturation basée sur l’utilisation

Configurer les compteurs

Ingérer des événements d’utilisation

Ingérer des événements par lots

Gestion des erreurs

Opérations asynchrones

Intégration Spring Boot

Classe de configuration

Couche de service

Ressources

GitHub Repository

API Reference

Discord Community

Report Issues

Assistance

Contribuer

​Installation

​Maven

​Gradle

​Démarrage rapide

​Fonctionnalités principales

Type Safety

Shared Client

Builder Pattern

Async Support

​Configuration

​Variables d’environnement

​Configuration manuelle

​Mode test

​Opérations courantes

​Créer une session de checkout

​Gérer les clients

​Gérer les abonnements

​Facturation basée sur l’utilisation

​Configurer les compteurs

​Ingérer des événements d’utilisation

​Ingérer des événements par lots

​Gestion des erreurs

​Opérations asynchrones

​Intégration Spring Boot

​Classe de configuration

​Couche de service

​Ressources

GitHub Repository

API Reference

Discord Community

Report Issues

​Assistance

​Contribuer

Installation

Maven

Gradle

Démarrage rapide

Fonctionnalités principales

Configuration

Variables d’environnement

Configuration manuelle

Mode test

Opérations courantes

Créer une session de checkout

Gérer les clients

Gérer les abonnements

Facturation basée sur l’utilisation

Configurer les compteurs

Ingérer des événements d’utilisation

Ingérer des événements par lots

Gestion des erreurs

Opérations asynchrones

Intégration Spring Boot

Classe de configuration

Couche de service

Ressources

Assistance

Contribuer