Java

O Java SDK oferece às aplicações Java acesso tipado à REST API do Dodo Payments. Ele usa tipos Java em todo o código: Optional para campos que podem estar ausentes, Stream para iterar sobre resultados e CompletableFuture para chamadas assíncronas.

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.118.0</version>
</dependency>

Gradle

Adicione a dependência ao seu build.gradle.kts:

build.gradle.kts

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

As versões do SDK adicionam suporte a alterações na API. Para encontrar a versão mais recente, consulte o Maven Central.

O SDK requer Java 8 ou posterior, portanto também funciona no Java 11, 17 e 21.

Início Rápido

Crie um cliente e, em seguida, 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.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() se conecta ao modo live, a menos que DODO_PAYMENTS_BASE_URL ou dodopayments.baseUrl indique o contrário. Para usar o modo de teste, consulte Modo de teste. Uma chave de API do modo de teste funciona somente no modo de teste.

Mantenha as chaves de API em variáveis de ambiente, propriedades do sistema ou em um gerenciador de segredos. Nunca as inclua diretamente no código-fonte.

Recursos principais

Type Safety

Classes tipadas de solicitação e resposta para verificações em tempo de compilação.

Shared Client

Crie um cliente e reutilize-o entre as solicitações: ele mantém a conexão e os pools de threads. Os objetos de solicitação e resposta são imutáveis.

Builder Pattern

Toda classe de solicitação tem um builder, e toBuilder() cria uma cópia modificada.

Async Support

client.async() retorna um cliente cujos métodos retornam CompletableFuture.

Configuração

Variáveis de ambiente

fromEnv() lê estas variáveis de ambiente ou as propriedades do sistema correspondentes. As propriedades do sistema têm precedência:

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

A chave de API vem de DODO_PAYMENTS_API_KEY ou dodopayments.apiKey. O segredo de assinatura do webhook vem de DODO_PAYMENTS_WEBHOOK_KEY ou dodopayments.webhookKey, e a URL base vem de DODO_PAYMENTS_BASE_URL ou dodopayments.baseUrl. Crie um cliente e reutilize-o, pois cada cliente tem seu próprio pool de conexões e pools de threads. Para verificar um webhook, passe o corpo bruto da solicitação e os cabeçalhos para client.webhooks().unwrap(UnwrapWebhookParams.builder().body(rawBody).headers(headers).build()), onde headers é um com.dodopayments.api.core.http.Headers. Ele verifica a assinatura com sua chave de webhook e retorna o evento analisado ou lança DodoPaymentsWebhookException. Sem cabeçalhos, unwrap não verifica a assinatura. client.webhooks().unsafeUnwrap(rawBody) analisa o corpo sem verificá-lo; portanto, use-o somente para testes. Consulte Webhooks.

Configuração manual

Defina cada opção no builder:

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

Por padrão, o cliente tenta novamente duas vezes e encerra a operação após 1 minuto. Ele tenta novamente em caso de erros de conexão e de respostas com status 408, 409, 429 ou 500 e superiores. Para substituir o tempo limite de uma chamada, passe RequestOptions.builder().timeout(Duration.ofSeconds(30)).build() como o segundo argumento do método. responseValidation(true) verifica antecipadamente se toda a resposta corresponde aos tipos esperados. Sem essa opção, o SDK lança DodoPaymentsInvalidDataException somente quando você lê uma propriedade com um tipo inesperado.

Modo de teste

Para usar o modo de teste (https://test.dodopayments.com), chame testMode() no builder:

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

Operações comuns

Os exemplos nesta seção usam o client do Início rápido.

Criar uma sessão de checkout

Crie uma sessão de checkout e redirecione o cliente para a URL de checkout retornada:

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() retorna um Optional<String>. Cada URL de checkout funciona uma vez e expira após 24 horas. Para ver todas as opções de sessão, consulte Sessões de checkout.

Gerenciar clientes

Crie um cliente com endereço de e-mail, nome e metadados e, em seguida, recupere-o pelo 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() + ")");

Gerenciar assinaturas

Crie uma assinatura com um link de pagamento e, em seguida, faça a cobrança se for uma assinatura sob demanda.

POST /subscriptions (o método subscriptions().create() do SDK) está obsoleto. Ele continua funcionando para integrações existentes, mas as novas integrações devem criar assinaturas por meio de uma Sessão de checkout.

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 está na menor unidade monetária, como centavos para USD ou paise para INR. Para cobrar $25.00, passe 2500.

subscriptions().charge(...) é destinado a assinaturas sob demanda. O Dodo Payments cobra automaticamente as outras assinaturas de acordo com o cronograma de cobrança do produto.

Cobrança baseada em uso

Configurar medidores

Crie um medidor que conte eventos e, em seguida, liste seus medidores. autoPager() itera sobre todos os medidores e busca mais páginas conforme necessário:

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

Envie um evento de uso para um cliente. Os valores dos metadados do evento são objetos JsonValue:

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

O eventId é a chave de idempotência; portanto, atribua um valor exclusivo a cada evento. Um timestamp com mais de 1 hora no passado ou mais de 5 minutos no futuro é rejeitado.

Ingerir eventos em lote

Envie até 1.000 eventos em uma única solicitação. Este exemplo usa as importações do exemplo anterior:

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

Tratamento de erros

O SDK lança exceções não verificadas. Para um status de erro, ele lança uma subclasse de DodoPaymentsServiceException, que contém statusCode(), headers() e body(). Capture as classes específicas que deseja tratar antes da classe base:

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

Statuses sem uma classe própria, como 409, lançam UnexpectedStatusCodeException. Falhas de rede lançam DodoPaymentsIoException, e respostas que o SDK não consegue interpretar lançam DodoPaymentsInvalidDataException. Todas essas classes estendem DodoPaymentsException.

O SDK tenta novamente em caso de erros de conexão e de respostas com status 408, 409, 429 ou 500 e superiores, duas vezes por padrão, com espera exponencial.

Operações assíncronas

Chame async() no cliente para obter um cliente assíncrono. Seus métodos retornam um 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;
});

Para criar um cliente assíncrono desde o início, use DodoPaymentsOkHttpClientAsync.fromEnv().

Integração com Spring Boot

Classe de configuração

Registre um cliente como um bean e escolha o ambiente a partir de uma propriedade:

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

Injete o cliente em um serviço:

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

Recursos

GitHub Repository

Código-fonte, versões e a lista completa de métodos.

API Reference

Todos os endpoints, parâmetros e respostas.

Discord Community

Faça perguntas e converse com outros desenvolvedores.

Report Issues

Relate bugs ou solicite recursos.

Suporte

Para obter ajuda com o Java SDK:

Discord: participe do servidor da comunidade para obter ajuda em tempo real.
E-mail: entre em contato pelo endereço support@dodopayments.com.
GitHub: abra uma issue no repositório.

Contribuição

Para contribuir, leia as diretrizes de contribuição.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Instalação

Maven

Gradle

Início Rápido

Recursos principais

Type Safety

Shared Client

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

Ingerir eventos em lote

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

Shared Client

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

​Ingerir eventos em lote

​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

Cobrança baseada em uso

Configurar medidores

Ingerir eventos de uso

Ingerir eventos em lote

Tratamento de erros

Operações assíncronas

Integração com Spring Boot

Classe de configuração

Camada de serviço

Recursos

Suporte

Contribuição