Java

Java SDKを使用すると、JavaアプリケーションからDodo Payments REST APIに型付きでアクセスできます。全体を通してJavaの型を使用しており、欠落する可能性のあるフィールドにはOptional、結果の反復処理にはStream、非同期呼び出しにはCompletableFutureを使用します。

インストール

Maven

依存関係をあなたのpom.xmlに追加します:

pom.xml

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

Gradle

依存関係をbuild.gradle.ktsに追加します。

build.gradle.kts

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

SDKのリリースでは、APIの変更への対応が追加されます。最新バージョンを確認するには、Maven Centralを参照してください。

SDKにはJava 8以降が必要です。そのため、Java 11、17、21でも実行できます。

クイックスタート

clientを作成してから、checkout sessionを作成します。

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()は、DODO_PAYMENTS_BASE_URLまたはdodopayments.baseUrlで別途指定されていない限り、live modeに接続します。test modeを使用するには、Test Modeを参照してください。test modeのAPI keyはtest modeでのみ使用できます。

API keyは環境変数、system property、またはsecrets managerに保存してください。ソースコードに直接記述しないでください。

Core Features

Type Safety

コンパイル時のチェックに対応した、型付きのrequest classとresponse class。

Shared Client

1つのclientを作成し、複数のrequestで再利用できます。clientはconnection poolとthread poolを保持します。request objectとresponse objectはimmutableです。

Builder Pattern

すべてのrequest classにはbuilderがあり、toBuilder()で変更したcopyを作成できます。

Async Support

client.async()は、各methodがCompletableFutureを返すclientを返します。

Configuration

Environment Variables

fromEnv()は、以下の環境変数、または対応するsystem propertyを読み取ります。system propertyが優先されます。

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

API keyはDODO_PAYMENTS_API_KEYまたはdodopayments.apiKeyから取得されます。webhook signing secretはDODO_PAYMENTS_WEBHOOK_KEYまたはdodopayments.webhookKeyから、base URLはDODO_PAYMENTS_BASE_URLまたはdodopayments.baseUrlから取得されます。1つのclientを作成して再利用してください。各clientは独自のconnection poolとthread poolを持つためです。 webhookを検証するには、raw request bodyとheadersをclient.webhooks().unwrap(UnwrapWebhookParams.builder().body(rawBody).headers(headers).build())に渡します。ここでheadersはcom.dodopayments.api.core.http.Headersです。webhook keyでsignatureを検証し、解析済みのeventを返します。検証に失敗した場合はDodoPaymentsWebhookExceptionをthrowします。headersを指定しない場合、unwrapはsignatureを検証しません。client.webhooks().unsafeUnwrap(rawBody)は検証せずにbodyを解析するため、テスト目的でのみ使用してください。Webhooksを参照してください。

Manual Configuration

builderで各optionを設定します。

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

デフォルトでは、clientは2回retryし、1分後にtimeoutします。connection errorと、status 408、409、429、または500以上のresponseをretryします。1回のcallでtimeoutを上書きするには、RequestOptions.builder().timeout(Duration.ofSeconds(30)).build()をmethodの2番目の引数として渡します。responseValidation(true)を使用すると、response全体が期待される型と一致するかを事前にチェックします。これを使用しない場合、SDKは想定外の型のpropertyを読み取ったときにのみDodoPaymentsInvalidDataExceptionをthrowします。

Test Mode

test mode（https://test.dodopayments.com）を使用するには、builderでtestMode()を呼び出します。

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

Common Operations

このセクションの例では、Quick Startで作成したclientを使用します。

Create a Checkout Session

checkout sessionを作成し、返されたcheckout URLにcustomerをredirectします。

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()はOptional<String>を返します。各checkout URLは1回のみ使用でき、24時間後に期限切れになります。すべてのsession optionについては、Checkout Sessionsを参照してください。

Manage Customers

email address、name、metadataを指定してcustomerを作成し、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() + ")");

Handle Subscriptions

payment linkを指定してsubscriptionを作成し、on-demand subscriptionの場合はchargeします。

POST /subscriptions（SDKのsubscriptions().create() method）はdeprecatedです。既存のintegrationでは引き続き動作しますが、新しいintegrationではCheckout Sessionを通じてsubscriptionを作成してください。

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は最小通貨単位で指定します。たとえばUSDではcent、INRではpaiseです。$25.00をchargeするには、2500を渡します。

subscriptions().charge(...)はon-demand subscriptions向けです。Dodo Paymentsは、その他のsubscriptionをproductのbilling scheduleに従って自動的に請求します。

Usage-Based Billing

Configure Meters

eventをカウントするmeterを作成し、meterを一覧表示します。autoPager()はすべてのmeterを反復処理し、必要に応じて追加のpageを取得します。

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

Ingest Usage Events

customerのusage eventを送信します。event metadataの値はJsonValue objectです。

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

eventIdはidempotency keyです。そのため、各eventには一意の値を指定してください。1時間を超えて過去の、または5分を超えて未来のtimestampは拒否されます。

Batch Ingest Events

1回のrequestで最大1,000件のeventを送信できます。この例では、前の例のimportを使用します。

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

Error Handling

SDKはunchecked exceptionをthrowします。error statusの場合、DodoPaymentsServiceExceptionのsubclassをthrowします。このclassにはstatusCode()、headers()、body()があります。base classより前に、処理したいspecific classをcatchしてください。

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

409など、独自のclassを持たないstatusではUnexpectedStatusCodeExceptionをthrowします。network failureではDodoPaymentsIoExceptionを、SDKが解釈できないresponseではDodoPaymentsInvalidDataExceptionをthrowします。これらはすべてDodoPaymentsExceptionをextendしています。

SDKは、connection errorとstatus 408、409、429、または500以上のresponseを、デフォルトでは指数バックオフを使用して2回retryします。

Async Operations

clientでasync()を呼び出すと、非同期clientを取得できます。そのmethodは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;
});

最初から非同期clientを作成するには、DodoPaymentsOkHttpClientAsync.fromEnv()を使用します。

Spring Boot Integration

Configuration Class

1つのclientをbeanとして登録し、propertyからenvironmentを選択します。

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

Service Layer

clientをserviceにinjectします。

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

Resources

GitHub Repository

source code、release、methodの完全な一覧。

API Reference

すべてのendpoint、parameter、response。

Discord Community

質問したり、他のdeveloperと交流したりできます。

Report Issues

bugを報告したり、featureをリクエストしたりできます。

Support

Java SDKに関するサポート：

Discord: リアルタイムのサポートを受けるには、community serverに参加してください。
Email: support@dodopayments.comに連絡してください。
GitHub: repositoryでissueを作成してください。

Contributing

contributeするには、contributing guidelinesをお読みください。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

インストール

Maven

Gradle

クイックスタート

Core Features

Type Safety

Shared Client

Builder Pattern

Async Support

Configuration

Environment Variables

Manual Configuration

Test Mode

Common Operations

Create a Checkout Session

Manage Customers

Handle Subscriptions

Usage-Based Billing

Configure Meters

Ingest Usage Events

Batch Ingest Events

Error Handling

Async Operations

Spring Boot Integration

Configuration Class

Service Layer

Resources

GitHub Repository

API Reference

Discord Community

Report Issues

Support

Contributing

​インストール

​Maven

​Gradle

​クイックスタート

​Core Features

Type Safety

Shared Client

Builder Pattern

Async Support

​Configuration

​Environment Variables

​Manual Configuration

​Test Mode

​Common Operations

​Create a Checkout Session

​Manage Customers

​Handle Subscriptions

​Usage-Based Billing

​Configure Meters

​Ingest Usage Events

​Batch Ingest Events

​Error Handling

​Async Operations

​Spring Boot Integration

​Configuration Class

​Service Layer

​Resources

GitHub Repository

API Reference

Discord Community

Report Issues

​Support

​Contributing

インストール

Maven

Gradle

クイックスタート

Core Features

Configuration

Environment Variables

Manual Configuration

Test Mode

Common Operations

Create a Checkout Session

Manage Customers

Handle Subscriptions

Usage-Based Billing

Configure Meters

Ingest Usage Events

Batch Ingest Events

Error Handling

Async Operations

Spring Boot Integration

Configuration Class

Service Layer

Resources

Support

Contributing