Java - Dodo Payments Documentation

Le SDK Java fournit un accès pratique et ergonomique à l’API REST de Dodo Payments pour les applications écrites en Java. Il utilise des fonctionnalités spécifiques à Java telles que Optional, Stream et CompletableFuture pour le développement Java moderne.

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.97.1</version>
</dependency>

Gradle

Ajoutez la dépendance dans votre build.gradle :

build.gradle.kts

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

Utilisez toujours la dernière version du SDK pour accéder aux fonctionnalités les plus récentes de Dodo Payments. Consultez Maven Central pour connaître la dernière version.

Le SDK prend en charge Java 8 et toutes les versions ultérieures, y compris Java 11, 17 et 21.

Démarrage rapide

Initialisez le client et créez une session de paiement :

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

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

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

Stockez toujours vos clés API en toute sécurité en utilisant des variables d’environnement, des propriétés système ou un système de gestion de configuration sécurisé. Ne les codez jamais en dur dans votre code source.

Fonctionnalités principales

Type Safety

API fortement typée avec sécurité à la compilation

Thread-Safe

Sécurisé pour une utilisation concurrente dans des applications multithread

Builder Pattern

Modèle builder intuitif pour construire des requêtes

Async Support

Prise en charge de CompletableFuture pour les opérations asynchrones

Configuration

Variables d’environnement

Configurez en utilisant des variables d’environnement ou des propriétés système :

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

Configuration manuelle

Configurez manuellement avec toutes les options :

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

Mode test

Configurez pour l’environnement de test/sandbox :

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

Opérations courantes

Créer une session de paiement

Générez une session de paiement :

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

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

Gérer les clients

Créez et récupérez des informations sur les clients :

import com.dodopayments.api.models.customers.Customer;
import com.dodopayments.api.models.customers.CustomerCreateParams;

// Create a customer
CustomerCreateParams createParams = CustomerCreateParams.builder()
    .email("customer@example.com")
    .name("John Doe")
    .putMetadata("user_id", "12345")
    .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 et gérez des abonnements récurrents :

import com.dodopayments.api.models.payments.AttachExistingCustomer;
import com.dodopayments.api.models.payments.BillingAddress;
import com.dodopayments.api.models.payments.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 dénomination monétaire (par exemple, centimes pour USD, paise pour INR). Pour facturer $25.00, passez 2500.

La facturation via subscriptions().charge(...) est destinée aux abonnements à la demande. Les abonnements programmés standard sont facturés automatiquement selon le barème de prix du produit.

Facturation Basée sur l’Usage

Configurer les Compteurs

Créez et gérez les compteurs pour suivre l’utilisation :

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

// Create API calls meter
MeterCreateParams apiMeterParams = MeterCreateParams.builder()
    .name("API Requests")
    .eventName("api_request")
    .aggregation("count")
    .putMetadata("category", "api_usage")
    .build();

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

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

Ingérer les Événements d’Usage

Suivre les événements personnalisés :

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

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

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

Ingérer les Événements en Lot

Ingérer plusieurs événements efficacement (maximum 1000 par demande) :

UsageEventIngestParams.Builder batchBuilder = UsageEventIngestParams.builder();

for (int i = 0; i < 100; i++) {
    batchBuilder.addEvent(UsageEventIngestParams.Event.builder()
        .eventId("batch_event_" + i + "_" + System.currentTimeMillis())
        .customerId("cus_abc123")
        .eventName("video_transcode")
        .timestamp(OffsetDateTime.now().minusMinutes(i))
        .putMetadata("video_id", "video_" + i)
        .putMetadata("duration_seconds", String.valueOf(120 + i))
        .build());
}

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

Gestion des Erreurs

Gestion complète des erreurs pour différents scénarios :

import com.dodopayments.api.errors.*;

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());
    // SDK automatically retries with backoff
} catch (InternalServerException e) {
    System.err.println("Server error: " + e.getMessage());
} catch (DodoPaymentsServiceException e) {
    System.err.println("API error: " + e.statusCode() + " - " + e.getMessage());
}

Le SDK réessaie automatiquement les requêtes en cas d’erreurs de connexion, 408, 409, 429 et d’erreurs 5xx avec retrait exponentiel.

Opérations Asynchrones

Utiliser CompletableFuture pour les opérations asynchrones :

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

Intégration avec Spring Boot

Classe de Configuration

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

import com.dodopayments.api.client.DodoPaymentsClient;
import com.dodopayments.api.models.checkoutsessions.*;
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

Voir le code source et contribuer

API Reference

Documentation complète de l’API

Discord Community

Obtenez de l’aide et connectez-vous avec les développeurs

Report Issues

Signaler des bugs ou demander des fonctionnalités

Support

Besoin d’aide avec le SDK Java ?

Discord : Rejoignez notre serveur communautaire pour un support en temps réel
Email : Contactez-nous à support@dodopayments.com
GitHub : Ouvrez une issue sur le dépôt

Contribuer

Nous accueillons les contributions ! Consultez les directives de contribution pour commencer.

​Installation

​Maven

​Gradle

​Démarrage rapide

​Fonctionnalités principales

Type Safety

Thread-Safe

Builder Pattern

Async Support

​Configuration

​Variables d’environnement

​Configuration manuelle

​Mode test

​Opérations courantes

​Créer une session de paiement

​Gérer les clients

​Gérer les abonnements

​Facturation Basée sur l’Usage

​Configurer les Compteurs

​Ingérer les Événements d’Usage

​Ingérer les Événements en Lot

​Gestion des Erreurs

​Opérations Asynchrones

​Intégration avec Spring Boot

​Classe de Configuration

​Couche de Service

​Ressources

GitHub Repository

API Reference

Discord Community

Report Issues

​Support

​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 paiement

Gérer les clients

Gérer les abonnements

Facturation Basée sur l’Usage

Configurer les Compteurs

Ingérer les Événements d’Usage

Ingérer les Événements en Lot

Gestion des Erreurs

Opérations Asynchrones

Intégration avec Spring Boot

Classe de Configuration

Couche de Service

Ressources

Support

Contribuer