Java

Il Java SDK offre alle applicazioni Java un accesso tipizzato alla REST API di Dodo Payments. Utilizza i tipi Java in tutto il codice: Optional per i campi che possono mancare, Stream per iterare sui risultati e CompletableFuture per le chiamate asincrone.

Installazione

Maven

Add the dependency to your pom.xml:

pom.xml

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

Gradle

Aggiungi la dipendenza al tuo build.gradle.kts:

build.gradle.kts

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

Le release dell’SDK aggiungono il supporto alle modifiche dell’API. Per trovare la versione più recente, consulta Maven Central.

L’SDK richiede Java 8 o versioni successive, quindi funziona anche con Java 11, 17 e 21.

Inizio Veloce

Crea un client, quindi crea una checkout session:

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() si connette alla modalità live, a meno che DODO_PAYMENTS_BASE_URL o dodopayments.baseUrl non indichino diversamente. Per usare la modalità test, consulta Test Mode. Una API key della modalità test funziona solo in modalità test.

Conserva le API key nelle variabili d’ambiente, nelle system properties o in un secrets manager. Non inserirle mai direttamente nel codice sorgente.

Funzionalità principali

Type Safety

Classi di request e response tipizzate per i controlli in fase di compilazione.

Shared Client

Crea un client e riutilizzalo per tutte le request: contiene il connection pool e i thread pool. Gli oggetti request e response sono immutabili.

Builder Pattern

Ogni classe request dispone di un builder e toBuilder() crea una copia modificata.

Async Support

client.async() restituisce un client i cui metodi restituiscono CompletableFuture.

Configurazione

Variabili d’ambiente

fromEnv() legge queste variabili d’ambiente o le system properties corrispondenti. Le system properties hanno la precedenza:

.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 API key proviene da DODO_PAYMENTS_API_KEY o dodopayments.apiKey. Il webhook signing secret proviene da DODO_PAYMENTS_WEBHOOK_KEY o dodopayments.webhookKey, mentre la base URL proviene da DODO_PAYMENTS_BASE_URL o dodopayments.baseUrl. Crea un client e riutilizzalo, perché ogni client dispone di un proprio connection pool e di propri thread pool. Per verificare un webhook, passa il raw request body e gli header a client.webhooks().unwrap(UnwrapWebhookParams.builder().body(rawBody).headers(headers).build()), dove headers è un com.dodopayments.api.core.http.Headers. Il metodo verifica la signature con la tua webhook key e restituisce l’evento analizzato oppure genera DodoPaymentsWebhookException. Senza header, unwrap non verifica la signature. client.webhooks().unsafeUnwrap(rawBody) analizza il body senza verificarlo, quindi usalo solo per i test. Consulta Webhooks.

Configurazione manuale

Imposta ogni opzione sul 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();

Per impostazione predefinita, il client esegue due retry e va in timeout dopo 1 minuto. Ripete le request in caso di errori di connessione e di response con status 408, 409, 429 o 500 e superiori. Per sostituire il timeout di una singola chiamata, passa RequestOptions.builder().timeout(Duration.ofSeconds(30)).build() come secondo argomento del metodo. responseValidation(true) verifica in anticipo che l’intera response corrisponda ai tipi previsti. Senza questa opzione, l’SDK genera DodoPaymentsInvalidDataException solo quando leggi una property con un tipo imprevisto.

Modalità test

Per usare la modalità test (https://test.dodopayments.com), chiama testMode() sul builder:

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

Operazioni comuni

Gli esempi di questa sezione utilizzano client di Quick Start.

Creare una checkout session

Crea una checkout session, quindi reindirizza il customer all’URL di checkout restituito:

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() restituisce un Optional<String>. Ogni URL di checkout funziona una sola volta e scade dopo 24 ore. Per tutte le opzioni della session, consulta Checkout Sessions.

Gestire i customer

Crea un customer con un indirizzo email, un nome e i metadata, quindi recuperalo tramite 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() + ")");

Gestire le subscription

Crea una subscription con un payment link, quindi addebitala se si tratta di una subscription on-demand.

POST /subscriptions (il metodo subscriptions().create() dell’SDK) è deprecato. Continua a funzionare per le integrazioni esistenti, ma per le nuove integrazioni è consigliabile creare le subscription 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 nell’unità minima della valuta, ad esempio in centesimi per USD o paise per INR. Per addebitare $25.00, passa 2500.

subscriptions().charge(...) è destinato alle subscription on-demand. Dodo Payments addebita automaticamente le altre subscription secondo la billing schedule del product.

Fatturazione basata sull’utilizzo

Configurare i meter

Crea un meter che conteggi gli eventi, quindi elenca i tuoi meter. autoPager() esegue l’iterazione su ogni meter e recupera altre pagine quando necessario:

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

Acquisire gli usage event

Invia un usage event per un customer. I valori dei metadata dell’evento sono oggetti 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 è la idempotency key, quindi assegna a ogni evento un valore univoco. Un timestamp antecedente di oltre 1 ora o successivo di oltre 5 minuti viene rifiutato.

Acquisire eventi in batch

Invia fino a 1.000 eventi in una singola request. Questo esempio utilizza gli import dell’esempio precedente:

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

Gestione degli errori

L’SDK genera unchecked exception. In caso di error status, genera una sottoclasse di DodoPaymentsServiceException, che dispone di statusCode(), headers() e body(). Intercetta le classi specifiche che vuoi gestire prima della base class:

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

Gli status senza una propria classe, come 409, generano UnexpectedStatusCodeException. Gli errori di rete generano DodoPaymentsIoException, mentre le response che l’SDK non riesce a interpretare generano DodoPaymentsInvalidDataException. Tutte queste classi estendono DodoPaymentsException.

L’SDK ripete le request in caso di errori di connessione e di response con status 408, 409, 429 o 500 e superiori, due volte per impostazione predefinita, con exponential backoff.

Operazioni asincrone

Chiama async() sul client per ottenere un client asincrono. I suoi metodi restituiscono 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;
});

Per creare un client asincrono fin dall’inizio, usa DodoPaymentsOkHttpClientAsync.fromEnv().

Integrazione con Spring Boot

Classe di configurazione

Registra un client come bean e scegli l’ambiente tramite una property:

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 layer

Inietta il client in 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);
    }
}

Risorse

GitHub Repository

Codice sorgente, release ed elenco completo dei metodi.

API Reference

Ogni endpoint, parametro e response.

Discord Community

Fai domande e parla con altri developer.

Report Issues

Segnala bug o richiedi funzionalità.

Supporto

Per ricevere assistenza sul Java SDK:

Discord: unisciti al server della community per ricevere assistenza in tempo reale.
Email: contatta support@dodopayments.com.
GitHub: apri una issue nel repository.

Contribuire

Per contribuire, leggi le linee guida per i contributi.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Installazione

Maven

Gradle

Inizio Veloce

Funzionalità principali

Type Safety

Shared Client

Builder Pattern

Async Support

Configurazione

Variabili d’ambiente

Configurazione manuale

Modalità test

Operazioni comuni

Creare una checkout session

Gestire i customer

Gestire le subscription

Fatturazione basata sull’utilizzo

Configurare i meter

Acquisire gli usage event

Acquisire eventi in batch

Gestione degli errori

Operazioni asincrone

Integrazione con Spring Boot

Classe di configurazione

Service layer

Risorse

GitHub Repository

API Reference

Discord Community

Report Issues

Supporto

Contribuire

​Installazione

​Maven

​Gradle

​Inizio Veloce

​Funzionalità principali

Type Safety

Shared Client

Builder Pattern

Async Support

​Configurazione

​Variabili d’ambiente

​Configurazione manuale

​Modalità test

​Operazioni comuni

​Creare una checkout session

​Gestire i customer

​Gestire le subscription

​Fatturazione basata sull’utilizzo

​Configurare i meter

​Acquisire gli usage event

​Acquisire eventi in batch

​Gestione degli errori

​Operazioni asincrone

​Integrazione con Spring Boot

​Classe di configurazione

​Service layer

​Risorse

GitHub Repository

API Reference

Discord Community

Report Issues

​Supporto

​Contribuire

Installazione

Maven

Gradle

Inizio Veloce

Funzionalità principali

Configurazione

Variabili d’ambiente

Configurazione manuale

Modalità test

Operazioni comuni

Creare una checkout session

Gestire i customer

Gestire le subscription

Fatturazione basata sull’utilizzo

Configurare i meter

Acquisire gli usage event

Acquisire eventi in batch

Gestione degli errori

Operazioni asincrone

Integrazione con Spring Boot

Classe di configurazione

Service layer

Risorse

Supporto

Contribuire