Java

Java SDK ger Java-applikationer typad åtkomst till Dodo Payments REST API. Det använder Java-typer genomgående: Optional för fält som kan saknas, Stream för att iterera över resultat och CompletableFuture för asynkrona anrop.

Installation

Maven

Lägg till beroendet i din pom.xml:

pom.xml

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

Gradle

Lägg till beroendet i din build.gradle.kts:

build.gradle.kts

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

SDK-versioner lägger till stöd för API-ändringar. Om du vill hitta den senaste versionen kan du kontrollera Maven Central.

SDK kräver Java 8 eller senare och körs därför även på Java 11, 17 och 21.

Snabbstart

Skapa en klient och skapa sedan en 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() ansluter till live-läge om inte DODO_PAYMENTS_BASE_URL eller dodopayments.baseUrl anger något annat. Information om hur du använder testläge finns i Testläge. En API-nyckel för testläge fungerar endast i testläge.

Förvara API-nycklar i miljövariabler, systemegenskaper eller en secrets manager. Hårdkoda dem aldrig i källkoden.

Kärnfunktioner

Type Safety

Typade request- och response-klasser för kontroller vid kompilering.

Shared Client

Skapa en klient och återanvänd den för flera anrop: den innehåller anslutningen samt trådpoolerna. Request- och response-objekt är oföränderliga.

Builder Pattern

Varje request-klass har en builder, och toBuilder() skapar en modifierad kopia.

Async Support

client.async() returnerar en klient vars metoder returnerar CompletableFuture.

Konfiguration

Miljövariabler

fromEnv() läser dessa miljövariabler eller motsvarande systemegenskaper. Systemegenskaper har företräde:

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

API-nyckeln hämtas från DODO_PAYMENTS_API_KEY eller dodopayments.apiKey. Webhook-signaturhemligheten hämtas från DODO_PAYMENTS_WEBHOOK_KEY eller dodopayments.webhookKey, och bas-URL:en från DODO_PAYMENTS_BASE_URL eller dodopayments.baseUrl. Skapa en klient och återanvänd den, eftersom varje klient har en egen anslutningspool och egna trådpooler. Om du vill verifiera en webhook skickar du den råa request body:n och headers till client.webhooks().unwrap(UnwrapWebhookParams.builder().body(rawBody).headers(headers).build()), där headers är ett com.dodopayments.api.core.http.Headers. Den kontrollerar signaturen med din webhook-nyckel och returnerar den tolkade händelsen eller kastar DodoPaymentsWebhookException. Utan headers verifierar unwrap inte signaturen. client.webhooks().unsafeUnwrap(rawBody) tolkar body:n utan att verifiera den, så använd den endast för testning. Se Webhooks.

Manuell konfiguration

Ange varje alternativ i buildern:

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

Som standard försöker klienten igen två gånger och avbryter efter 1 minut. Den försöker igen vid anslutningsfel och svar med status 408, 409, 429 eller 500 och högre. Om du vill åsidosätta timeouten för ett anrop skickar du RequestOptions.builder().timeout(Duration.ofSeconds(30)).build() som metodens andra argument. responseValidation(true) kontrollerar i förväg att hela svaret överensstämmer med de förväntade typerna. Utan den kastar SDK DodoPaymentsInvalidDataException först när du läser en egenskap med en oväntad typ.

Testläge

Om du vill använda testläge (https://test.dodopayments.com) anropar du testMode() på buildern:

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

Vanliga åtgärder

Exemplen i det här avsnittet använder client från Snabbstart.

Skapa en checkout-session

Skapa en checkout-session och omdirigera sedan kunden till den returnerade checkout-URL:en:

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() returnerar en Optional<String>. Varje checkout-URL kan användas en gång och upphör att gälla efter 24 timmar. Information om alla sessionsalternativ finns i Checkout Sessions.

Hantera kunder

Skapa en kund med e-postadress, namn och metadata och hämta den sedan med dess 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() + ")");

Hantera prenumerationer

Skapa en prenumeration med en payment link och debitera den sedan om det är en on-demand-prenumeration.

POST /subscriptions (SDK:ts subscriptions().create()-metod) är föråldrad. Den fungerar fortfarande för befintliga integrationer, men nya integrationer bör skapa prenumerationer via en 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 anges i den minsta valutaenheten, till exempel cent för USD eller paise för INR. Om du vill debitera $25.00 skickar du 2500.

subscriptions().charge(...) används för on-demand-prenumerationer. Dodo Payments debiterar andra prenumerationer automatiskt enligt produktens debiteringsschema.

Användningsbaserad debitering

Konfigurera mätare

Skapa en mätare som räknar händelser och lista sedan dina mätare. autoPager() itererar över varje mätare och hämtar fler sidor vid behov:

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

Importera användningshändelser

Skicka en användningshändelse för en kund. Värdena i händelsens metadata är JsonValue-objekt:

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 är idempotency key, så ge varje händelse ett unikt värde. En timestamp som ligger mer än 1 timme bakåt i tiden eller mer än 5 minuter framåt i tiden avvisas.

Importera händelser i batch

Skicka upp till 1 000 händelser i en request. Det här exemplet använder importerna från föregående exempel:

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

Felhantering

SDK kastar okontrollerade undantag. Vid en felstatus kastar den en subklass av DodoPaymentsServiceException, som innehåller statusCode(), headers() och body(). Fånga de specifika klasser du vill hantera före basklassen:

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

Statusar utan en egen klass, som 409, kastar UnexpectedStatusCodeException. Nätverksfel kastar DodoPaymentsIoException, och svar som SDK inte kan tolka kastar DodoPaymentsInvalidDataException. Alla dessa ärver från DodoPaymentsException.

SDK försöker igen vid anslutningsfel och svar med status 408, 409, 429 eller 500 och högre, som standard två gånger, med exponentiell backoff.

Asynkrona åtgärder

Anropa async() på klienten för att hämta en asynkron klient. Dess metoder returnerar en 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;
});

Om du vill skapa en asynkron klient direkt använder du DodoPaymentsOkHttpClientAsync.fromEnv().

Spring Boot-integration

Konfigurationsklass

Registrera en klient som en bean och välj miljö från en egenskap:

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

Servicelager

Injicera klienten i en tjänst:

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

Resurser

GitHub Repository

Källkod, versioner och den fullständiga metodlistan.

API Reference

Alla endpoints, parametrar och svar.

Discord Community

Ställ frågor och prata med andra utvecklare.

Report Issues

Rapportera buggar eller föreslå funktioner.

Support

För hjälp med Java SDK:

Discord: Gå med i community-servern för hjälp i realtid.
E-post: Kontakta support@dodopayments.com.
GitHub: Skapa ett ärende i arkivet.

Bidra

Om du vill bidra kan du läsa riktlinjerna för bidrag.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Installation

Maven

Gradle

Snabbstart

Kärnfunktioner

Type Safety

Shared Client

Builder Pattern

Async Support

Konfiguration

Miljövariabler

Manuell konfiguration

Testläge

Vanliga åtgärder

Skapa en checkout-session

Hantera kunder

Hantera prenumerationer

Användningsbaserad debitering

Konfigurera mätare

Importera användningshändelser

Importera händelser i batch

Felhantering

Asynkrona åtgärder

Spring Boot-integration

Konfigurationsklass

Servicelager

Resurser

GitHub Repository

API Reference

Discord Community

Report Issues

Support

Bidra

​Installation

​Maven

​Gradle

​Snabbstart

​Kärnfunktioner

Type Safety

Shared Client

Builder Pattern

Async Support

​Konfiguration

​Miljövariabler

​Manuell konfiguration

​Testläge

​Vanliga åtgärder

​Skapa en checkout-session

​Hantera kunder

​Hantera prenumerationer

​Användningsbaserad debitering

​Konfigurera mätare

​Importera användningshändelser

​Importera händelser i batch

​Felhantering

​Asynkrona åtgärder

​Spring Boot-integration

​Konfigurationsklass

​Servicelager

​Resurser

GitHub Repository

API Reference

Discord Community

Report Issues

​Support

​Bidra

Installation

Maven

Gradle

Snabbstart

Kärnfunktioner

Konfiguration

Miljövariabler

Manuell konfiguration

Testläge

Vanliga åtgärder

Skapa en checkout-session

Hantera kunder

Hantera prenumerationer

Användningsbaserad debitering

Konfigurera mätare

Importera användningshändelser

Importera händelser i batch

Felhantering

Asynkrona åtgärder

Spring Boot-integration

Konfigurationsklass

Servicelager

Resurser

Support

Bidra