Java

SDK Java cung cấp quyền truy cập thuận tiện và dễ sử dụng vào Dodo Payments REST API cho các ứng dụng viết bằng Java. Nó sử dụng các tính năng đặc thù của Java như Optional, Stream và CompletableFuture cho phát triển Java hiện đại.

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

Gradle

Thêm phần phụ thuộc vào build.gradle:

build.gradle.kts

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

Luôn sử dụng phiên bản SDK mới nhất để truy cập các tính năng mới nhất của Dodo Payments. Kiểm tra Maven Central để biết phiên bản mới nhất.

SDK hỗ trợ Java 8 và tất cả các phiên bản sau đó, bao gồm Java 11, 17 và 21.

Bắt đầu nhanh

Khởi tạo client và tạo một phiên giao dịch thanh toán:

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

Luôn lưu trữ khóa API một cách an toàn bằng biến môi trường, thuộc tính hệ thống hoặc hệ thống quản lý cấu hình an toàn. Không bao giờ mã hóa cứng chúng vào mã nguồn của bạn.

Tính năng chính

Type Safety

API kiểu tường minh với đảm bảo an toàn thời gian biên dịch

Thread-Safe

An toàn khi sử dụng đồng thời trong các ứng dụng đa luồng

Builder Pattern

Mẫu builder trực quan để xây dựng các yêu cầu

Async Support

Hỗ trợ CompletableFuture cho các thao tác bất đồng bộ

Cấu hình

Biến môi trường

Cấu hình bằng cách sử dụng biến môi trường hoặc thuộc tính hệ thống:

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

Cấu hình thủ công

Cấu hình thủ công với tất cả các tùy chọn:

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

Chế độ thử nghiệm

Cấu hình cho môi trường Test Mode:

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

Các thao tác thông thường

Tạo một phiên giao dịch thanh toán

Tạo một phiên giao dịch thanh toán:

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

Quản lý khách hàng

Tạo và truy xuất thông tin khách hàng:

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

Xử lý đăng ký

Tạo và quản lý các đăng ký định kỳ:

POST /subscriptions (phương thức subscriptions.create của SDK) đã không còn được dùng. Phương thức này vẫn hoạt động với các integration hiện có, nhưng các integration mới nên tạo subscription thông qua 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 biểu thị theo mệnh giá tiền tệ thấp nhất (ví dụ: cents đối với USD, paise đối với INR). Để tính phí $25.00, hãy truyền 2500.

Tính phí thông qua subscriptions().charge(...) dành cho on-demand subscriptions. Các subscription được lên lịch tiêu chuẩn sẽ được tính phí tự động dựa trên lịch định giá 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 và quản lý meter để theo dõi mức sử dụng:

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

Tiếp nhận sự kiện mức sử dụng

Theo dõi các sự kiện tùy chỉnh:

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

Tiếp nhận hàng loạt sự kiện

Tiếp nhận nhiều sự kiện một cách hiệu quả (tối đa 1000 sự kiện trong mỗi request):

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

Xử lý lỗi

Xử lý lỗi toàn diện cho các tình huống khác nhau:

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

SDK sẽ tự động retry các request khi xảy ra lỗi kết nối, lỗi 408, 409, 429 và lỗi 5xx với thời gian chờ tăng dần theo cấp số nhân.

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

Sử dụng CompletableFuture cho các thao tác bất đồng bộ:

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ích hợp Spring Boot

Class cấu hình

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

Tầng service

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

Tài nguyên

GitHub Repository

Xem mã nguồn và đóng góp

API Reference

Tài liệu API đầy đủ

Discord Community

Nhận trợ giúp và kết nối với các developer

Report Issues

Báo cáo lỗi hoặc yêu cầu tính năng

Hỗ trợ

Bạn cần trợ giúp với Java SDK?

Discord: Tham gia community server của chúng tôi để được hỗ trợ theo thời gian thực
Email: Liên hệ với chúng tôi qua support@dodopayments.com
GitHub: Mở issue trên repository

Đóng góp

Chúng tôi hoan nghênh các đóng góp! Hãy xem hướng dẫn đóng góp để bắt đầu.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Cài đặt

Maven

Gradle

Bắt đầu nhanh

Tính năng chính

Type Safety

Thread-Safe

Builder Pattern

Async Support

Cấu hình

Biến môi trường

Cấu hình thủ công

Chế độ thử nghiệm

Các thao tác thông thường

Tạo một phiên giao dịch thanh toán

Quản lý khách hàng

Xử lý đăng ký

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

Cấu hình Meter

Tiếp nhận sự kiện mức sử dụng

Tiếp nhận hàng loạt sự kiện

Xử lý lỗi

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

Tích hợp Spring Boot

Class cấu hình

Tầng service

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 chính

Type Safety

Thread-Safe

Builder Pattern

Async Support

​Cấu hình

​Biến môi trường

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

​Chế độ thử nghiệm

​Các thao tác thông thường

​Tạo một phiên giao dịch thanh toán

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

​Xử lý đăng ký

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

​Cấu hình Meter

​Tiếp nhận sự kiện mức sử dụng

​Tiếp nhận hàng loạt sự kiện

​Xử lý lỗi

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

​Tích hợp Spring Boot

​Class cấu hình

​Tầng service

​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 chính

Cấu hình

Biến môi trường

Cấu hình thủ công

Chế độ thử nghiệm

Các thao tác thông thường

Tạo một phiên giao dịch thanh toán

Quản lý khách hàng

Xử lý đăng ký

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

Cấu hình Meter

Tiếp nhận sự kiện mức sử dụng

Tiếp nhận hàng loạt sự kiện

Xử lý lỗi

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

Tích hợp Spring Boot

Class cấu hình

Tầng service

Tài nguyên

Hỗ trợ

Đóng góp