Java

El SDK de Java proporciona acceso conveniente y ergonómico a la API REST de Dodo Payments para aplicaciones escritas en Java. Utiliza características específicas de Java como Optional, Stream y CompletableFuture para el desarrollo moderno en Java.

Instalación

Maven

Agrega la dependencia a tu pom.xml:

pom.xml

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

Gradle

Agrega la dependencia a tu build.gradle:

build.gradle.kts

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

Utiliza siempre la versión más reciente del SDK para acceder a las funciones más nuevas de Dodo Payments. Consulta Maven Central para conocer la última versión.

El SDK es compatible con Java 8 y todas las versiones posteriores, incluido Java 11, 17 y 21.

Inicio Rápido

Inicializa el cliente y crea una sesión de pago:

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

Almacena siempre tus claves API de forma segura utilizando variables de entorno, propiedades del sistema o un sistema seguro de gestión de configuración. Nunca las incrustes en tu código fuente.

Características Principales

Type Safety

API fuertemente tipada con seguridad en tiempo de compilación

Thread-Safe

Seguro para uso concurrente en aplicaciones multihilo

Builder Pattern

Patrón builder intuitivo para construir solicitudes

Async Support

Compatibilidad con CompletableFuture para operaciones asíncronas

Configuración

Variables de Entorno

Configura utilizando variables de entorno o propiedades del 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();

Configuración Manual

Configura manualmente con todas las opciones:

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

Modo de Prueba

Configura el entorno de prueba:

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

Operaciones Comunes

Crear una Sesión de Pago

Genera una sesión de pago:

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

Gestionar Clientes

Crea y recupera información de clientes:

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

Manejar Suscripciones

Crea y gestiona suscripciones recurrentes:

POST /subscriptions (el método subscriptions.create del SDK) está obsoleto. Sigue funcionando para las integraciones existentes, pero las nuevas integraciones deben crear suscripciones mediante 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 se expresa en la denominación monetaria más baja (por ejemplo, centavos para USD y paise para INR). Para cobrar $25.00, pasa 2500.

El cobro mediante subscriptions().charge(...) está destinado a suscripciones bajo demanda. Las suscripciones programadas estándar se cobran automáticamente según el calendario de precios del producto.

Facturación basada en el uso

Configurar medidores

Crea y administra medidores para realizar un seguimiento del uso:

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

Ingestar eventos de uso

Registra eventos personalizados:

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

Ingestar eventos por lotes

Ingesta varios eventos de forma eficiente (máximo 1000 por solicitud):

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

Manejo de errores

Manejo integral de errores para distintos escenarios:

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

El SDK reintenta automáticamente las solicitudes cuando se producen errores de conexión y errores 408, 409, 429 y 5xx, con un backoff exponencial.

Operaciones asíncronas

Usa CompletableFuture para las operaciones asíncronas:

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

Integración con Spring Boot

Clase de configuración

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

Capa de servicio

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

Recursos

GitHub Repository

Consulta el código fuente y contribuye

API Reference

Consulta la documentación completa de la API

Discord Community

Obtén ayuda y conéctate con otros desarrolladores

Report Issues

Informa de errores o solicita funcionalidades

Soporte

¿Necesitas ayuda con el Java SDK?

Discord: Únete a nuestro servidor de la comunidad para obtener soporte en tiempo real
Email: Contáctanos en support@dodopayments.com
GitHub: Abre un issue en el repositorio

Contribuciones

¡Damos la bienvenida a las contribuciones! Consulta las directrices para contribuir para comenzar.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Instalación

Maven

Gradle

Inicio Rápido

Características Principales

Type Safety

Thread-Safe

Builder Pattern

Async Support

Configuración

Variables de Entorno

Configuración Manual

Modo de Prueba

Operaciones Comunes

Crear una Sesión de Pago

Gestionar Clientes

Manejar Suscripciones

Facturación basada en el uso

Configurar medidores

Ingestar eventos de uso

Ingestar eventos por lotes

Manejo de errores

Operaciones asíncronas

Integración con Spring Boot

Clase de configuración

Capa de servicio

Recursos

GitHub Repository

API Reference

Discord Community

Report Issues

Soporte

Contribuciones

​Instalación

​Maven

​Gradle

​Inicio Rápido

​Características Principales

Type Safety

Thread-Safe

Builder Pattern

Async Support

​Configuración

​Variables de Entorno

​Configuración Manual

​Modo de Prueba

​Operaciones Comunes

​Crear una Sesión de Pago

​Gestionar Clientes

​Manejar Suscripciones

​Facturación basada en el uso

​Configurar medidores

​Ingestar eventos de uso

​Ingestar eventos por lotes

​Manejo de errores

​Operaciones asíncronas

​Integración con Spring Boot

​Clase de configuración

​Capa de servicio

​Recursos

GitHub Repository

API Reference

Discord Community

Report Issues

​Soporte

​Contribuciones

Instalación

Maven

Gradle

Inicio Rápido

Características Principales

Configuración

Variables de Entorno

Configuración Manual

Modo de Prueba

Operaciones Comunes

Crear una Sesión de Pago

Gestionar Clientes

Manejar Suscripciones

Facturación basada en el uso

Configurar medidores

Ingestar eventos de uso

Ingestar eventos por lotes

Manejo de errores

Operaciones asíncronas

Integración con Spring Boot

Clase de configuración

Capa de servicio

Recursos

Soporte

Contribuciones