자바 - Dodo Payments Documentation

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에 dependency를 추가합니다:

build.gradle.kts

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

SDK release에는 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에 보관하세요. 소스 코드에 절대 하드코딩하지 마세요.

핵심 기능

Type Safety

컴파일 시 검사를 위한 타입이 지정된 request 및 response 클래스입니다.

Shared Client

client 하나를 생성하고 모든 request에서 재사용하세요. client가 connection pool과 thread pool을 유지합니다. Request 및 response 객체는 immutable입니다.

Builder Pattern

모든 request 클래스에는 builder가 있으며, toBuilder()는 수정된 복사본을 생성합니다.

Async Support

client.async()는 메서드가 CompletableFuture를 반환하는 client를 반환합니다.

구성

환경 변수

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에서 가져옵니다. 각 client에는 자체 connection pool과 thread pool이 있으므로 client 하나를 생성하고 재사용하세요. 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를 파싱하므로 testing 목적으로만 사용하세요. Webhooks를 참조하세요.

수동 구성

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

기본적으로 client는 두 번 retry하며 1분 후 timeout됩니다. connection error와 status가 408, 409, 429 또는 500 이상인 response를 retry합니다. 한 번의 call에 대한 timeout을 재정의하려면 메서드의 두 번째 argument로 RequestOptions.builder().timeout(Duration.ofSeconds(30)).build()를 전달하세요. responseValidation(true)는 전체 response가 예상된 type과 일치하는지 미리 확인합니다. 이 옵션이 없으면 SDK는 예상과 다른 type의 property를 읽을 때만 DodoPaymentsInvalidDataException를 throw합니다.

Test Mode

test mode(https://test.dodopayments.com)를 사용하려면 builder에서 testMode()를 호출합니다:

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

일반적인 작업

이 섹션의 예제는 Quick Start의 client를 사용합니다.

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은 한 번만 작동하며 24시간 후 만료됩니다. 모든 session 옵션은 Checkout Sessions를 참조하세요.

Customer 관리

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

Subscription 처리

payment link로 subscription을 생성한 다음 on-demand subscription인 경우 charge합니다.

POST /subscriptions(SDK의 subscriptions().create() 메서드)는 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에서는 cents, INR에서는 paise입니다. $25.00을 charge하려면 2500를 전달하세요.

subscriptions().charge(...)는 on-demand subscriptions에 사용됩니다. Dodo Payments는 product의 billing schedule에 따라 다른 subscription을 자동으로 청구합니다.

사용량 기반 Billing

Meter 구성

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

Usage Event 수집

customer의 usage event를 전송합니다. Event metadata 값은 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());

eventId는 idempotency key이므로 각 event에 고유한 값을 지정하세요. 현재 시점보다 1시간 넘게 이전이거나 5분 넘게 이후인 timestamp는 거부됩니다.

Event 일괄 수집

한 번의 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하며, 이 클래스에는 statusCode(), headers() 및 body()가 있습니다. 처리하려는 구체적인 클래스를 base 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를 throw하고, SDK가 해석할 수 없는 response는 DodoPaymentsInvalidDataException를 throw합니다. 이 모든 class는 DodoPaymentsException를 extend합니다.

SDK는 connection error와 status가 408, 409, 429 또는 500 이상인 response를 기본적으로 두 번, exponential backoff와 함께 retry합니다.

비동기 작업

client에서 async()를 호출하면 asynchronous client를 가져옵니다. 해당 메서드는 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;
});

처음부터 asynchronous client를 생성하려면 DodoPaymentsOkHttpClientAsync.fromEnv()를 사용하세요.

Spring Boot 통합

구성 클래스

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

리소스

GitHub Repository

소스 코드, release 및 전체 메서드 목록입니다.

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 guidelines를 읽어보세요.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

자바

설치

Maven

Gradle

빠른 시작

핵심 기능

Type Safety

Shared Client

Builder Pattern

Async Support

구성

환경 변수

수동 구성

Test Mode

일반적인 작업

Checkout Session 생성

Customer 관리

Subscription 처리

사용량 기반 Billing

Meter 구성

Usage Event 수집

Event 일괄 수집

Error Handling

비동기 작업

Spring Boot 통합

구성 클래스

Service Layer

리소스

GitHub Repository

API Reference

Discord Community

Report Issues

Support

기여

​설치

​Maven

​Gradle

​빠른 시작

​핵심 기능

Type Safety

Shared Client

Builder Pattern

Async Support

​구성

​환경 변수

​수동 구성

​Test Mode

​일반적인 작업

​Checkout Session 생성

​Customer 관리

​Subscription 처리

​사용량 기반 Billing

​Meter 구성

​Usage Event 수집

​Event 일괄 수집

​Error Handling

​비동기 작업

​Spring Boot 통합

​구성 클래스

​Service Layer

​리소스

GitHub Repository

API Reference

Discord Community

Report Issues

​Support

​기여

설치

Maven

Gradle

빠른 시작

핵심 기능

구성

환경 변수

수동 구성

Test Mode

일반적인 작업

Checkout Session 생성

Customer 관리

Subscription 처리

사용량 기반 Billing

Meter 구성

Usage Event 수집

Event 일괄 수집

Error Handling

비동기 작업

Spring Boot 통합

구성 클래스

Service Layer

리소스

Support

기여