Java

Java SDK cung cấp cho các ứng dụng Java quyền truy cập có kiểu đến REST API của Dodo Payments. SDK sử dụng các kiểu Java xuyên suốt: Optional cho các trường có thể bị thiếu, Stream để lặp qua các kết quả và CompletableFuture cho các lệnh gọi bất đồng bộ.

Cài đặt

Maven

Thêm phần phụ thuộc vào pom.xml:

pom.xml

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

Gradle

Thêm dependency vào build.gradle.kts của bạn:

build.gradle.kts

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

Các bản phát hành SDK bổ sung hỗ trợ cho những thay đổi của API. Để tìm phiên bản mới nhất, hãy kiểm tra Maven Central.

SDK yêu cầu Java 8 trở lên, vì vậy cũng chạy được trên Java 11, 17 và 21.

Bắt đầu nhanh

Tạo một client, sau đó tạo một phiên 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() kết nối với live mode trừ khi DODO_PAYMENTS_BASE_URL hoặc dodopayments.baseUrl chỉ định khác. Để sử dụng test mode, hãy xem Test Mode. API key của test mode chỉ hoạt động trong test mode.

Lưu API key trong biến môi trường, system properties hoặc secrets manager. Không bao giờ hardcode chúng trong source code.

Tính năng cốt lõi

Type Safety

Các class request và response có kiểu để kiểm tra tại thời điểm biên dịch.

Shared Client

Tạo một client và tái sử dụng client đó cho các request: client quản lý connection pool và thread pool. Các object request và response là bất biến.

Builder Pattern

Mỗi class request đều có một builder, và toBuilder() tạo một bản sao đã chỉnh sửa.

Async Support

client.async() trả về một client có các method trả về CompletableFuture.

Cấu hình

Biến môi trường

fromEnv() đọc các biến môi trường này hoặc system properties tương ứng. System properties được ưu tiên:

.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 được lấy từ DODO_PAYMENTS_API_KEY hoặc dodopayments.apiKey. Webhook signing secret được lấy từ DODO_PAYMENTS_WEBHOOK_KEY hoặc dodopayments.webhookKey, còn base URL được lấy từ DODO_PAYMENTS_BASE_URL hoặc dodopayments.baseUrl. Hãy tạo một client và tái sử dụng client đó, vì mỗi client có connection pool và thread pool riêng. Để xác minh một webhook, truyền raw request body và headers vào client.webhooks().unwrap(UnwrapWebhookParams.builder().body(rawBody).headers(headers).build()), trong đó headers là một com.dodopayments.api.core.http.Headers. Method này kiểm tra chữ ký bằng webhook key của bạn và trả về event đã được phân tích, hoặc ném ra DodoPaymentsWebhookException. Nếu không có headers, unwrap sẽ không xác minh chữ ký. client.webhooks().unsafeUnwrap(rawBody) phân tích body mà không xác minh, vì vậy chỉ sử dụng method này để testing. Xem Webhooks.

Cấu hình thủ công

Thiết lập từng tùy chọn trên 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();

Theo mặc định, client thử lại hai lần và timeout sau 1 phút. Client thử lại khi xảy ra lỗi kết nối và khi nhận được response có status 408, 409, 429 hoặc 500 trở lên. Để ghi đè timeout cho một lần gọi, truyền RequestOptions.builder().timeout(Duration.ofSeconds(30)).build() làm đối số thứ hai của method. responseValidation(true) kiểm tra trước rằng toàn bộ response khớp với các kiểu dự kiến. Nếu không có tùy chọn này, SDK chỉ ném DodoPaymentsInvalidDataException khi bạn đọc một property có kiểu không mong đợi.

Test Mode

Để sử dụng test mode (https://test.dodopayments.com), hãy gọi testMode() trên builder:

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

Các thao tác phổ biến

Các ví dụ trong phần này sử dụng client từ Quick Start.

Tạo phiên Checkout

Tạo một phiên checkout, sau đó chuyển hướng khách hàng đến checkout URL được trả về:

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() trả về một Optional<String>. Mỗi checkout URL chỉ sử dụng được một lần và hết hạn sau 24 giờ. Để xem mọi tùy chọn của phiên, hãy xem Checkout Sessions.

Quản lý khách hàng

Tạo một khách hàng với email, tên và metadata, sau đó truy xuất khách hàng bằng 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() + ")");

Xử lý gói đăng ký

Tạo một gói đăng ký với payment link, sau đó charge gói này nếu đó là gói đăng ký on-demand.

POST /subscriptions (method subscriptions().create() của SDK) đã lỗi thời. Method này vẫn hoạt động với các integration hiện có, nhưng integration mới nên tạo gói đăng ký thông qua một 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 được tính theo đơn vị tiền tệ nhỏ nhất, chẳng hạn như cents đối với USD hoặc paise đối với INR. Để charge $25.00, hãy truyền 2500.

subscriptions().charge(...) dành cho on-demand subscriptions. Dodo Payments tự động lập hóa đơn cho các gói đăng ký khác theo lịch thanh toán của sản phẩm.

Tính phí dựa trên mức sử dụng

Cấu hình meter

Tạo một meter để đếm các event, sau đó liệt kê các meter của bạn. autoPager() lặp qua mọi meter và tìm nạp thêm các trang khi cần:

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

Nạp event sử dụng

Gửi một event sử dụng cho khách hàng. Các giá trị metadata của event là các object 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 là idempotency key, vì vậy hãy cung cấp một giá trị duy nhất cho mỗi event. Một timestamp cách thời điểm hiện tại hơn 1 giờ về trước hoặc hơn 5 phút trong tương lai sẽ bị từ chối.

Nạp event theo lô

Gửi tối đa 1.000 event trong một request. Ví dụ này sử dụng các import từ ví dụ trước:

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

Xử lý lỗi

SDK ném ra các unchecked exception. Khi có error status, SDK ném ra một subclass của DodoPaymentsServiceException, trong đó có statusCode(), headers() và body(). Hãy catch các class cụ thể mà bạn muốn xử lý trước base class:

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

Các status không có class riêng, chẳng hạn 409, sẽ ném UnexpectedStatusCodeException. Lỗi mạng sẽ ném DodoPaymentsIoException, còn các response mà SDK không thể diễn giải sẽ ném DodoPaymentsInvalidDataException. Tất cả các class này đều mở rộng DodoPaymentsException.

SDK thử lại các lỗi kết nối và response có status 408, 409, 429 hoặc 500 trở lên, mặc định hai lần, với exponential backoff.

Các thao tác bất đồng bộ

Gọi async() trên client để lấy một client bất đồng bộ. Các method của client này trả về một 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;
});

Để tạo client bất đồng bộ ngay từ đầu, hãy sử dụng DodoPaymentsOkHttpClientAsync.fromEnv().

Tích hợp Spring Boot

Class cấu hình

Đăng ký một client dưới dạng bean và chọn environment từ một property:

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

Inject client vào một service:

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

Tài nguyên

GitHub Repository

Source code, các bản phát hành và danh sách method đầy đủ.

API Reference

Mọi endpoint, parameter và response.

Discord Community

Đặt câu hỏi và trao đổi với các developer khác.

Report Issues

Báo cáo bug hoặc yêu cầu tính năng.

Hỗ trợ

Để được hỗ trợ về Java SDK:

Discord: Tham gia community server để được hỗ trợ theo thời gian thực.
Email: Liên hệ support@dodopayments.com.
GitHub: Mở issue trên repository.

Đóng góp

Để đóng góp, hãy đọc hướng dẫn đóng góp.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Cài đặt

Maven

Gradle

Bắt đầu nhanh

Tính năng cốt lõi

Type Safety

Shared Client

Builder Pattern

Async Support

Cấu hình

Biến môi trường

Cấu hình thủ công

Test Mode

Các thao tác phổ biến

Tạo phiên Checkout

Quản lý khách hàng

Xử lý gói đăng ký

Tính phí dựa trên mức sử dụng

Cấu hình meter

Nạp event sử dụng

Nạp event theo lô

Xử lý lỗi

Các thao tác bất đồng bộ

Tích hợp Spring Boot

Class cấu hình

Service layer

Tài nguyên

GitHub Repository

API Reference

Discord Community

Report Issues

Hỗ trợ

Đóng góp

​Cài đặt

​Maven

​Gradle

​Bắt đầu nhanh

​Tính năng cốt lõi

Type Safety

Shared Client

Builder Pattern

Async Support

​Cấu hình

​Biến môi trường

​Cấu hình thủ công

​Test Mode

​Các thao tác phổ biến

​Tạo phiên Checkout

​Quản lý khách hàng

​Xử lý gói đăng ký

​Tính phí dựa trên mức sử dụng

​Cấu hình meter

​Nạp event sử dụng

​Nạp event theo lô

​Xử lý lỗi

​Các thao tác bất đồng bộ

​Tích hợp Spring Boot

​Class cấu hình

​Service layer

​Tài nguyên

GitHub Repository

API Reference

Discord Community

Report Issues

​Hỗ trợ

​Đóng góp

Cài đặt

Maven

Gradle

Bắt đầu nhanh

Tính năng cốt lõi

Cấu hình

Biến môi trường

Cấu hình thủ công

Test Mode

Các thao tác phổ biến

Tạo phiên Checkout

Quản lý khách hàng

Xử lý gói đăng ký

Tính phí dựa trên mức sử dụng

Cấu hình meter

Nạp event sử dụng

Nạp event theo lô

Xử lý lỗi

Các thao tác bất đồng bộ

Tích hợp Spring Boot

Class cấu hình

Service layer

Tài nguyên

Hỗ trợ

Đóng góp