Java

Java SDK memberikan akses bertipe kepada aplikasi Java ke REST API Dodo Payments. SDK ini menggunakan tipe Java secara menyeluruh: Optional untuk field yang mungkin tidak ada, Stream untuk melakukan iterasi pada hasil, dan CompletableFuture untuk panggilan asinkron.

Instalasi

Maven

Tambahkan dependensi ke pom.xml:

pom.xml

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

Gradle

Tambahkan dependency ke build.gradle.kts Anda:

build.gradle.kts

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

Rilis SDK menambahkan dukungan untuk perubahan API. Untuk menemukan versi terbaru, lihat Maven Central.

SDK memerlukan Java 8 atau yang lebih baru, sehingga juga dapat berjalan di Java 11, 17, dan 21.

Memulai Cepat

Buat client, lalu buat 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() terhubung ke live mode kecuali DODO_PAYMENTS_BASE_URL atau dodopayments.baseUrl menyatakan sebaliknya. Untuk menggunakan test mode, lihat Test Mode. API key test mode hanya berfungsi dalam test mode.

Simpan API key dalam environment variable, system property, atau secrets manager. Jangan pernah menuliskannya secara hardcode di source code.

Fitur Inti

Type Safety

Class request dan response bertipe untuk pemeriksaan saat compile time.

Shared Client

Buat satu client dan gunakan kembali di seluruh request: client tersebut menyimpan connection pool dan thread pool. Object request dan response bersifat immutable.

Builder Pattern

Setiap class request memiliki builder, dan toBuilder() membuat salinan yang telah dimodifikasi.

Async Support

client.async() mengembalikan client yang method-nya menghasilkan CompletableFuture.

Konfigurasi

Environment Variable

fromEnv() membaca environment variable ini atau system property yang sesuai. System property memiliki prioritas lebih tinggi:

.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 berasal dari DODO_PAYMENTS_API_KEY atau dodopayments.apiKey. Webhook signing secret berasal dari DODO_PAYMENTS_WEBHOOK_KEY atau dodopayments.webhookKey, sedangkan base URL berasal dari DODO_PAYMENTS_BASE_URL atau dodopayments.baseUrl. Buat satu client dan gunakan kembali, karena setiap client memiliki connection pool dan thread pool sendiri. Untuk memverifikasi webhook, teruskan raw request body dan header ke client.webhooks().unwrap(UnwrapWebhookParams.builder().body(rawBody).headers(headers).build()), dengan headers sebagai com.dodopayments.api.core.http.Headers. Method ini memeriksa signature dengan webhook key Anda dan mengembalikan event yang telah di-parse, atau melempar DodoPaymentsWebhookException. Tanpa header, unwrap tidak memverifikasi signature. client.webhooks().unsafeUnwrap(rawBody) mem-parse body tanpa memverifikasinya, jadi gunakan hanya untuk testing. Lihat Webhooks.

Konfigurasi Manual

Atur setiap opsi pada 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();

Secara default, client mencoba ulang dua kali dan mengalami timeout setelah 1 menit. Client mencoba ulang connection error dan response dengan status 408, 409, 429, atau 500 ke atas. Untuk mengganti timeout pada satu call, teruskan RequestOptions.builder().timeout(Duration.ofSeconds(30)).build() sebagai argumen kedua method. responseValidation(true) memeriksa sejak awal apakah seluruh response sesuai dengan tipe yang diharapkan. Tanpanya, SDK hanya melempar DodoPaymentsInvalidDataException saat Anda membaca property dengan tipe yang tidak sesuai.

Test Mode

Untuk menggunakan test mode (https://test.dodopayments.com), panggil testMode() pada builder:

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

Operasi Umum

Contoh dalam bagian ini menggunakan client dari Quick Start.

Membuat Checkout Session

Buat checkout session, lalu arahkan customer ke checkout URL yang dikembalikan:

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() mengembalikan Optional<String>. Setiap checkout URL hanya dapat digunakan sekali dan kedaluwarsa setelah 24 jam. Untuk setiap opsi session, lihat Checkout Sessions.

Mengelola Customer

Buat customer dengan alamat email, nama, dan metadata, lalu ambil kembali menggunakan 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() + ")");

Menangani Subscription

Buat subscription dengan payment link, lalu kenakan biaya jika subscription tersebut bersifat on-demand.

POST /subscriptions (method subscriptions().create() pada SDK) deprecated. Method ini masih berfungsi untuk integrasi yang sudah ada, tetapi integrasi baru sebaiknya membuat subscription melalui 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 menggunakan unit mata uang terkecil, seperti cents untuk USD atau paise untuk INR. Untuk mengenakan biaya $25.00, teruskan 2500.

subscriptions().charge(...) digunakan untuk on-demand subscriptions. Dodo Payments menagih subscription lainnya secara otomatis sesuai jadwal penagihan produk.

Penagihan Berbasis Penggunaan

Mengonfigurasi Meter

Buat meter yang menghitung event, lalu tampilkan daftar meter Anda. autoPager() melakukan iterasi pada setiap meter dan mengambil halaman tambahan sesuai kebutuhan:

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

Memasukkan Usage Event

Kirim usage event untuk customer. Nilai metadata event adalah 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 adalah idempotency key, jadi berikan nilai unik untuk setiap event. timestamp yang lebih dari 1 jam di masa lalu atau lebih dari 5 menit di masa mendatang akan ditolak.

Memasukkan Event Secara Batch

Kirim hingga 1.000 event dalam satu request. Contoh ini menggunakan import dari contoh sebelumnya:

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

Penanganan Error

SDK melempar unchecked exception. Untuk status error, SDK melempar subclass dari DodoPaymentsServiceException, yang memiliki statusCode(), headers(), dan body(). Tangkap class khusus yang ingin Anda tangani sebelum 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());
}

Status tanpa class khusus, seperti 409, melempar UnexpectedStatusCodeException. Network failure melempar DodoPaymentsIoException, sedangkan response yang tidak dapat diinterpretasikan oleh SDK melempar DodoPaymentsInvalidDataException. Semua exception ini merupakan turunan dari DodoPaymentsException.

SDK mencoba ulang connection error dan response dengan status 408, 409, 429, atau 500 ke atas, secara default sebanyak dua kali, dengan exponential backoff.

Operasi Asinkron

Panggil async() pada client untuk mendapatkan client asinkron. Method-nya mengembalikan 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;
});

Untuk membuat client asinkron sejak awal, gunakan DodoPaymentsOkHttpClientAsync.fromEnv().

Integrasi Spring Boot

Class Konfigurasi

Daftarkan satu client sebagai bean, lalu pilih environment dari sebuah 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 ke dalam 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);
    }
}

Resource

GitHub Repository

Source code, rilis, dan daftar method lengkap.

API Reference

Setiap endpoint, parameter, dan response.

Discord Community

Ajukan pertanyaan dan berdiskusi dengan developer lain.

Report Issues

Laporkan bug atau ajukan fitur.

Dukungan

Untuk mendapatkan bantuan terkait Java SDK:

Discord: Bergabunglah dengan community server untuk mendapatkan bantuan secara real-time.
Email: Hubungi support@dodopayments.com.
GitHub: Buat issue di repository.

Berkontribusi

Untuk berkontribusi, baca contributing guidelines.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Instalasi

Maven

Gradle

Memulai Cepat

Fitur Inti

Type Safety

Shared Client

Builder Pattern

Async Support

Konfigurasi

Environment Variable

Konfigurasi Manual

Test Mode

Operasi Umum

Membuat Checkout Session

Mengelola Customer

Menangani Subscription

Penagihan Berbasis Penggunaan

Mengonfigurasi Meter

Memasukkan Usage Event

Memasukkan Event Secara Batch

Penanganan Error

Operasi Asinkron

Integrasi Spring Boot

Class Konfigurasi

Service Layer

Resource

GitHub Repository

API Reference

Discord Community

Report Issues

Dukungan

Berkontribusi

​Instalasi

​Maven

​Gradle

​Memulai Cepat

​Fitur Inti

Type Safety

Shared Client

Builder Pattern

Async Support

​Konfigurasi

​Environment Variable

​Konfigurasi Manual

​Test Mode

​Operasi Umum

​Membuat Checkout Session

​Mengelola Customer

​Menangani Subscription

​Penagihan Berbasis Penggunaan

​Mengonfigurasi Meter

​Memasukkan Usage Event

​Memasukkan Event Secara Batch

​Penanganan Error

​Operasi Asinkron

​Integrasi Spring Boot

​Class Konfigurasi

​Service Layer

​Resource

GitHub Repository

API Reference

Discord Community

Report Issues

​Dukungan

​Berkontribusi

Instalasi

Maven

Gradle

Memulai Cepat

Fitur Inti

Konfigurasi

Environment Variable

Konfigurasi Manual

Test Mode

Operasi Umum

Membuat Checkout Session

Mengelola Customer

Menangani Subscription

Penagihan Berbasis Penggunaan

Mengonfigurasi Meter

Memasukkan Usage Event

Memasukkan Event Secara Batch

Penanganan Error

Operasi Asinkron

Integrasi Spring Boot

Class Konfigurasi

Service Layer

Resource

Dukungan

Berkontribusi