Java - Dodo Payments Documentation

O SDK Java fornece acesso conveniente e ergonômico à API REST de pagamentos Dodo para aplicações escritas em Java. Ele utiliza recursos específicos do Java, como Optional, Stream e CompletableFuture para o desenvolvimento moderno em Java.

Instalação

Maven

Adicione a dependência ao seu pom.xml:

pom.xml

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

Gradle

Adicione a dependência ao seu build.gradle:

build.gradle.kts

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

Sempre use a versão mais recente do SDK para acessar os recursos mais novos do Dodo Payments. Consulte o Maven Central para ver a versão mais recente.

O SDK oferece suporte ao Java 8 e a todas as versões posteriores, incluindo Java 11, 17 e 21.

Início Rápido

Inicialize o cliente e crie uma sessão de 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());

Sempre armazene suas chaves de API com segurança usando variáveis de ambiente, propriedades do sistema ou um sistema seguro de gerenciamento de configurações. Nunca codifique-as diretamente no seu código-fonte.

Recursos Principais

Type Safety

API fortemente tipada com segurança em tempo de compilação

Thread-Safe

Seguro para uso concorrente em aplicações multithread

Builder Pattern

Padrão de builder intuitivo para construção de requisições

Async Support

Suporte a CompletableFuture para operações assíncronas

Configuração

Variáveis de Ambiente

Configure usando variáveis de ambiente ou propriedades do 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();

Configuração Manual

Configure manualmente com todas as opções:

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 Teste

Configure para o ambiente de teste/sandbox:

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

Operações Comuns

Criar uma Sessão de Checkout

Gere uma sessão de checkout:

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

Gerenciar Clientes

Crie e recupere informações 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() + ")");

Gerenciar Assinaturas

Crie e gerencie assinaturas recorrentes:

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 é expresso na menor denominação da moeda (por exemplo, centavos para USD, paise para INR). Para cobrar $25.00, passe 2500.

Cobrar via subscriptions().charge(...) é destinado para assinaturas sob demanda. Assinaturas programadas padrão são cobradas automaticamente com base no cronograma de preços do produto.

Cobrança Baseada em Uso

Configurar Medidores

Crie e gerencie medidores para rastrear o 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()));

Ingerir Eventos de Uso

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

Ingestão em Lote de Eventos

Ingerir vários eventos de forma eficiente (máximo de 1000 por solicitação):

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

Tratamento de Erros

Tratamento abrangente de erros para diferentes cenários:

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

O SDK tenta automaticamente novas solicitações em casos de erros de conexão, 408, 409, 429 e erros 5xx com um backoff exponencial.

Operações Assíncronas

Use CompletableFuture para operações assí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;
});

Integração com Spring Boot

Classe de Configuração

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

Camada de Serviço

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

Veja o código-fonte e contribua

API Reference

Documentação completa da API

Discord Community

Obtenha ajuda e conecte-se com os desenvolvedores

Report Issues

Reporte bugs ou solicite recursos

Suporte

Precisa de ajuda com o Java SDK?

Discord: Junte-se ao nosso servidor comunitário para suporte em tempo real
Email: Entre em contato pelo support@dodopayments.com
GitHub: Abra uma issue no repositório

Contribuições

Acolhemos contribuições! Confira as diretrizes de contribuição para começar.

​Instalação

​Maven

​Gradle

​Início Rápido

​Recursos Principais

Type Safety

Thread-Safe

Builder Pattern

Async Support

​Configuração

​Variáveis de Ambiente

​Configuração Manual

​Modo de Teste

​Operações Comuns

​Criar uma Sessão de Checkout

​Gerenciar Clientes

​Gerenciar Assinaturas

​Cobrança Baseada em Uso

​Configurar Medidores

​Ingerir Eventos de Uso

​Ingestão em Lote de Eventos

​Tratamento de Erros

​Operações Assíncronas

​Integração com Spring Boot

​Classe de Configuração

​Camada de Serviço

​Recursos

GitHub Repository

API Reference

Discord Community

Report Issues

​Suporte

​Contribuições

Instalação

Maven

Gradle

Início Rápido

Recursos Principais

Configuração

Variáveis de Ambiente

Configuração Manual

Modo de Teste

Operações Comuns

Criar uma Sessão de Checkout

Gerenciar Clientes

Gerenciar Assinaturas

Cobrança Baseada em Uso

Configurar Medidores

Ingerir Eventos de Uso

Ingestão em Lote de Eventos

Tratamento de Erros

Operações Assíncronas

Integração com Spring Boot

Classe de Configuração

Camada de Serviço

Recursos

Suporte

Contribuições