Java - Dodo Payments Documentation

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 para el entorno de prueba/sandbox:

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("prod_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:

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 se expresa en la denominación más baja de la moneda (por ejemplo, centavos para USD, paise para INR). Para cobrar $25.00, pase 2500.

Cobrar a través de subscriptions().charge(...) está destinado para suscripciones bajo demanda. Las suscripciones programadas estándar se facturan automáticamente según el programa de precios del producto.

Facturación Basada en Uso

Configurar Medidores

Crea y gestiona medidores para rastrear el uso:

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

Ingestar Eventos de Uso

Rastrea eventos personalizados:

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

Ingestar Eventos en Lote

Ingesta múltiple de eventos eficientemente (máximo 1000 por solicitud):

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

Manejo de Errores

Manejo de errores comprensivo para diferentes 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 solicitudes en errores de conexión, 408, 409, 429 y errores 5xx con retroceso exponencial.

Operaciones Asíncronas

Usa CompletableFuture para 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

Ver código fuente y contribuir

API Reference

Documentación completa de API

Discord Community

Obtén ayuda y conéctate con desarrolladores

Report Issues

Reporta errores o solicita funciones

Soporte

¿Necesitas ayuda con el SDK de Java?

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

Contribuyendo

¡Damos la bienvenida a las contribuciones! Revisa las directrices de contribución para comenzar.

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

​Configurar Medidores

​Ingestar Eventos de Uso

​Ingestar Eventos en Lote

​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

​Contribuyendo

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 Uso

Configurar Medidores

Ingestar Eventos de Uso

Ingestar Eventos en Lote

Manejo de Errores

Operaciones Asíncronas

Integración con Spring Boot

Clase de Configuración

Capa de Servicio

Recursos

Soporte

Contribuyendo