Java

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 Test Mode:

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

POST /subscriptions (o método subscriptions.create do SDK) está obsoleto. Ele ainda funciona para integrações existentes, mas novas integrações devem criar assinaturas por meio de uma 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 é expresso na menor denominação da moeda (por exemplo, centavos para USD e paise para INR). Para cobrar $25.00, passe 2500.

A cobrança via subscriptions().charge(...) destina-se a assinaturas sob demanda. As assinaturas agendadas padrão são cobradas automaticamente com base no cronograma de preços do produto.

Faturamento baseado em uso

Configurar medidores

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

Ingerir eventos de uso

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

Ingestão em lote de eventos

Ingira vários eventos com eficiência (máximo de 1000 por solicitação):

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

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 novamente as solicitações automaticamente em caso de erros de conexão, erros 408, 409, 429 e 5xx, usando 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

Visualize o código-fonte e contribua

API Reference

Documentação completa da API

Discord Community

Obtenha ajuda e conecte-se com desenvolvedores

Report Issues

Relate bugs ou solicite recursos

Suporte

Precisa de ajuda com o Java SDK?

Discord: participe do nosso servidor da comunidade para obter suporte em tempo real
E-mail: entre em contato conosco pelo e-mail support@dodopayments.com
GitHub: abra uma issue no repositório

Contribuição

Aceitamos contribuições! Consulte as diretrizes de contribuição para começar.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

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

Faturamento baseado 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ção

​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

​Faturamento baseado 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ção

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

Faturamento baseado 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ção