Java

L’SDK Java fornisce un accesso conveniente ed ergonomico all’API REST di Dodo Payments per le applicazioni scritte in Java. Utilizza funzionalità specifiche di Java come Optional, Stream e CompletableFuture per lo sviluppo moderno in Java.

Installazione

Maven

Add the dependency to your pom.xml:

pom.xml

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

Gradle

Add the dependency to your build.gradle:

build.gradle.kts

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

Usa sempre l’ultima versione dell’SDK per accedere alle funzionalità più recenti di Dodo Payments. Verifica su Maven Central la versione più recente.

L’SDK supporta Java 8 e tutte le versioni successive, incluse Java 11, 17 e 21.

Inizio Veloce

Inizializza il client e crea una sessione di checkout:

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

Conserva sempre le chiavi API in modo sicuro utilizzando variabili d’ambiente, proprietà di sistema o un sistema di gestione delle configurazioni sicuro. Non inserirle mai direttamente nel codice sorgente.

Caratteristiche Principali

Type Safety

API fortemente tipizzata con sicurezza a tempo di compilazione

Thread-Safe

Sicuro per l’uso concorrente in applicazioni multi-thread

Builder Pattern

Pattern builder intuitivo per costruire le richieste

Async Support

Supporto CompletableFuture per operazioni asincrone

Configurazione

Variabili d’Ambiente

Configura utilizzando variabili d’ambiente o proprietà di sistema:

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

Configurazione Manuale

Configura manualmente con tutte le opzioni:

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

Modalità di Test

Configura per l’ambiente Test Mode:

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

Operazioni Comuni

Crea una Sessione di Checkout

Genera una sessione di checkout:

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

Gestisci i Clienti

Crea e recupera informazioni sui clienti:

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

Gestisci Abbonamenti

Crea e gestisci abbonamenti ricorrenti:

POST /subscriptions (il metodo subscriptions.create dell’SDK) è deprecato. Continua a funzionare per le integrazioni esistenti, ma per le nuove integrazioni è consigliabile creare abbonamenti tramite una Checkout Session.

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 è espresso nella denominazione più bassa della valuta (ad esempio, centesimi per USD, paise per INR). Per addebitare 25,00 $, passa 2500.

L’addebito tramite subscriptions().charge(...) è destinato agli abbonamenti on-demand. Gli abbonamenti standard programmati vengono fatturati automaticamente in base al piano tariffario del prodotto.

Fatturazione basata sull’utilizzo

Configura i meter

Crea e gestisci i meter per monitorare l’utilizzo:

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

Acquisisci gli eventi di utilizzo

Monitora gli eventi personalizzati:

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

Acquisisci gli eventi in batch

Acquisisci più eventi in modo efficiente (massimo 1000 per richiesta):

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

Gestione degli errori

Gestione completa degli errori per diversi scenari:

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

L’SDK riprova automaticamente le richieste in caso di errori di connessione, errori 408, 409, 429 e 5xx, utilizzando un backoff esponenziale.

Operazioni asincrone

Usa CompletableFuture per le operazioni asincrone:

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

Integrazione con Spring Boot

Classe di configurazione

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

Livello del servizio

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

Risorse

GitHub Repository

Visualizza il codice sorgente e contribuisci

API Reference

Documentazione completa dell’API

Discord Community

Ricevi assistenza e connettiti con gli sviluppatori

Report Issues

Segnala bug o richiedi funzionalità

Supporto

Hai bisogno di aiuto con l’SDK Java?

Discord: unisciti al nostro server della community per ricevere assistenza in tempo reale
Email: contattaci all’indirizzo support@dodopayments.com
GitHub: apri una segnalazione nel repository

Contribuire

Accogliamo con piacere i contributi! Consulta le linee guida per i contributi per iniziare.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Installazione

Maven

Gradle

Inizio Veloce

Caratteristiche Principali

Type Safety

Thread-Safe

Builder Pattern

Async Support

Configurazione

Variabili d’Ambiente

Configurazione Manuale

Modalità di Test

Operazioni Comuni

Crea una Sessione di Checkout

Gestisci i Clienti

Gestisci Abbonamenti

Fatturazione basata sull’utilizzo

Configura i meter

Acquisisci gli eventi di utilizzo

Acquisisci gli eventi in batch

Gestione degli errori

Operazioni asincrone

Integrazione con Spring Boot

Classe di configurazione

Livello del servizio

Risorse

GitHub Repository

API Reference

Discord Community

Report Issues

Supporto

Contribuire

​Installazione

​Maven

​Gradle

​Inizio Veloce

​Caratteristiche Principali

Type Safety

Thread-Safe

Builder Pattern

Async Support

​Configurazione

​Variabili d’Ambiente

​Configurazione Manuale

​Modalità di Test

​Operazioni Comuni

​Crea una Sessione di Checkout

​Gestisci i Clienti

​Gestisci Abbonamenti

​Fatturazione basata sull’utilizzo

​Configura i meter

​Acquisisci gli eventi di utilizzo

​Acquisisci gli eventi in batch

​Gestione degli errori

​Operazioni asincrone

​Integrazione con Spring Boot

​Classe di configurazione

​Livello del servizio

​Risorse

GitHub Repository

API Reference

Discord Community

Report Issues

​Supporto

​Contribuire

Installazione

Maven

Gradle

Inizio Veloce

Caratteristiche Principali

Configurazione

Variabili d’Ambiente

Configurazione Manuale

Modalità di Test

Operazioni Comuni

Crea una Sessione di Checkout

Gestisci i Clienti

Gestisci Abbonamenti

Fatturazione basata sull’utilizzo

Configura i meter

Acquisisci gli eventi di utilizzo

Acquisisci gli eventi in batch

Gestione degli errori

Operazioni asincrone

Integrazione con Spring Boot

Classe di configurazione

Livello del servizio

Risorse

Supporto

Contribuire