Kotlin - Dodo Payments Documentation

Kotlin SDK menyediakan akses praktis ke REST API Dodo Payments dari aplikasi yang ditulis dalam Kotlin. SDK ini mendukung nilai nullable, Sequence, fungsi suspend, dan fitur khusus Kotlin lainnya untuk penggunaan yang ergonomis.

Instalasi

Gradle (Kotlin DSL)

Tambahkan dependensi ke build.gradle.kts Anda:

build.gradle.kts

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

Maven

Tambahkan dependensi ke pom.xml Anda:

pom.xml

<dependency>
  <groupId>com.dodopayments.api</groupId>
  <artifactId>dodo-payments-kotlin</artifactId>
  <version>1.97.1</version>
</dependency>

Selalu gunakan versi SDK terbaru untuk mengakses fitur terbaru dari Dodo Payments. Periksa Maven Central untuk mendapatkan versi terbaru.

SDK ini memerlukan Java 8 atau yang lebih baru dan kompatibel dengan platform JVM dan Android.

Mulai Cepat

Inisialisasi client dan buat checkout session:

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)
val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv()

val params: CheckoutSessionRequest = CheckoutSessionRequest.builder()
    .addProductCart(ProductItemReq.builder()
        .productId("product_id")
        .quantity(1)
        .build())
    .build()
    
val checkoutSessionResponse: CheckoutSessionResponse = client.checkoutSessions().create(params)
println(checkoutSessionResponse.sessionId())

Selalu simpan API keys Anda dengan aman menggunakan environment variables atau konfigurasi terenkripsi. Jangan pernah memasukkannya ke version control.

Fitur Utama

Coroutines

Dukungan penuh untuk Kotlin coroutines dalam operasi asinkron

Null Safety

Manfaatkan null safety Kotlin untuk penanganan error yang andal

Extension Functions

Ekstensi Kotlin idiomatis untuk fungsionalitas yang lebih baik

Data Classes

Data classes yang type-safe dengan dukungan copy dan destructuring

Konfigurasi

Dari Environment Variables

Inisialisasi dari environment variables atau system properties:

val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv()

Konfigurasi Manual

Konfigurasikan secara manual dengan semua opsi:

import java.time.Duration

val client = DodoPaymentsOkHttpClient.builder()
    .bearerToken("your_api_key_here")
    .baseUrl("https://live.dodopayments.com")
    .maxRetries(3)
    .timeout(Duration.ofSeconds(30))
    .build()

Test Mode

Konfigurasikan untuk lingkungan Test Mode:

val testClient = DodoPaymentsOkHttpClient.builder()
    .fromEnv()
    .testMode()
    .build()

Timeout dan Retry

Konfigurasikan secara global atau per-request:

import com.dodopayments.api.core.RequestOptions

// Global configuration
val client = DodoPaymentsOkHttpClient.builder()
    .fromEnv()
    .timeout(Duration.ofSeconds(45))
    .maxRetries(3)
    .build()

// Per-request timeout override
val product = client.products().retrieve(
    "pdt_123",
    RequestOptions.builder()
        .timeout(Duration.ofSeconds(10))
        .build()
)

Operasi Umum

Buat Checkout Session

Buat checkout session:

val params = CheckoutSessionRequest.builder()
    .addProductCart(ProductItemReq.builder()
        .productId("pdt_123")
        .quantity(1)
        .build())
    .returnUrl("https://yourdomain.com/return")
    .build()

val session = client.checkoutSessions().create(params)
println("Checkout URL: ${session.checkoutUrl()}")

Buat Product

Buat product dengan konfigurasi terperinci:

import com.dodopayments.api.models.products.Price
import com.dodopayments.api.models.products.Product
import com.dodopayments.api.models.products.ProductCreateParams
import com.dodopayments.api.models.misc.Currency
import com.dodopayments.api.models.misc.TaxCategory
import com.dodopayments.api.models.misc.TimeInterval

val createParams = ProductCreateParams.builder()
    .name("Premium Subscription")
    .description("Monthly subscription with all features")
    .price(
        Price.RecurringPrice.builder()
            .currency(Currency.USD)
            .price(2999) // $29.99 in cents
            .discount(0L)
            .purchasingPowerParity(false)
            .paymentFrequencyCount(1)
            .paymentFrequencyInterval(TimeInterval.MONTH)
            .subscriptionPeriodCount(1)
            .subscriptionPeriodInterval(TimeInterval.MONTH)
            .build()
    )
    .taxCategory(TaxCategory.DIGITAL_PRODUCTS)
    .build()

val product: Product = client.products().create(createParams)
println("Created product ID: ${product.productId()}")

Aktifkan License Key

Aktifkan license keys untuk customer:

import com.dodopayments.api.models.licenses.LicenseActivateParams
import com.dodopayments.api.models.licenses.LicenseActivateResponse

val activateParams = LicenseActivateParams.builder()
    .licenseKey("XXXX-XXXX-XXXX-XXXX")
    .name("user-laptop-01")
    .build()

try {
    val activationResult: LicenseActivateResponse = client.licenses()
        .activate(activateParams)

    println("License activated successfully")
    println("Instance ID: ${activationResult.id()}")
    println("License key ID: ${activationResult.licenseKeyId()}")
} catch (e: UnprocessableEntityException) {
    println("License activation failed: ${e.message}")
}

Tangani Subscription

Buat dan kelola recurring subscriptions:

POST /subscriptions (metode subscriptions.create pada SDK) sudah deprecated. Metode ini masih berfungsi untuk integrasi yang sudah ada, tetapi integrasi baru harus 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.SubscriptionCreateParams

// Create a subscription
val 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)
    .build()

val subscription = client.subscriptions().create(subscriptionParams)
println("Subscription ID: ${subscription.subscriptionId()}")

// Charge an on-demand subscription
// productPrice is in the lowest currency denomination (e.g., 2500 = $25.00 USD)
val chargeParams = SubscriptionChargeParams.builder()
    .subscriptionId(subscription.subscriptionId())
    .productPrice(2500)
    .build()

val chargeResponse = client.subscriptions().charge(chargeParams)
println("Payment ID: ${chargeResponse.paymentId()}")

billing memerlukan minimal kode country ISO yang terdiri dari dua huruf. Gunakan AttachExistingCustomer untuk mengaitkan customer yang sudah ada, atau NewCustomer untuk membuatnya. productPrice dinyatakan dalam denominasi mata uang terkecil.

Penagihan Berbasis Penggunaan

Mencatat Event Penggunaan

Lacak penggunaan untuk meter:

import com.dodopayments.api.models.usageevents.EventInput
import com.dodopayments.api.models.usageevents.UsageEventIngestParams

val usageParams = UsageEventIngestParams.builder()
    .addEvent(EventInput.builder()
        .customerId("cust_456")
        .eventId("event_123")
        .eventName("api_call")
        .build())
    .build()

client.usageEvents().ingest(usageParams)
println("Usage event recorded")

Operasi Asinkron

Async Client

Gunakan async client untuk operasi berbasis coroutine:

import com.dodopayments.api.client.DodoPaymentsClientAsync
import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClientAsync
import kotlinx.coroutines.runBlocking

val asyncClient: DodoPaymentsClientAsync = DodoPaymentsOkHttpClientAsync.fromEnv()

runBlocking {
    val customer = asyncClient.customers().retrieve("cust_123")
    println("Customer email: ${customer.email()}")
}

Penanganan Error

Tangani error dengan exception handling Kotlin:

import com.dodopayments.api.errors.*

try {
    val payment = client.payments().create(params)
    println("Success: ${payment.paymentId()}")
} catch (e: AuthenticationException) {
    println("Authentication failed: ${e.message}")
} catch (e: InvalidRequestException) {
    println("Invalid request: ${e.message}")
    e.parameter?.let { println("Parameter: $it") }
} catch (e: RateLimitException) {
    println("Rate limit exceeded, retry after: ${e.retryAfter}")
} catch (e: DodoPaymentsServiceException) {
    println("API error: ${e.statusCode()} - ${e.message}")
}

Functional Error Handling

Gunakan Result untuk functional error handling:

fun safeCreatePayment(client: DodoPaymentsClient): Result<Payment> = runCatching {
    client.payments().create(params)
}

// Usage
safeCreatePayment(client)
    .onSuccess { payment -> println("Created: ${payment.paymentId()}") }
    .onFailure { error -> println("Error: ${error.message}") }

Gunakan runCatching Kotlin untuk pendekatan yang lebih fungsional terhadap error handling dengan tipe Result.

Integrasi Android

Gunakan dengan aplikasi Android:

import android.app.Application
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.dodopayments.api.client.DodoPaymentsClient
import kotlinx.coroutines.launch

class PaymentViewModel(application: Application) : ViewModel() {
    private val client = DodoPaymentsOkHttpClient.builder()
        .bearerToken(BuildConfig.DODO_API_KEY)
        .build()
    
    fun createCheckout(productId: String) {
        viewModelScope.launch {
            try {
                val session = client.async().checkoutSessions().create(params)
                // Open checkout URL in browser or WebView
                openUrl(session.checkoutUrl())
            } catch (e: Exception) {
                handleError(e)
            }
        }
    }
}

Validasi Response

Aktifkan validasi response:

import com.dodopayments.api.core.RequestOptions

// Per-request validation
val product = client.products().retrieve(
    "pdt_123",
    RequestOptions.builder()
        .responseValidation(true)
        .build()
)

// Or validate explicitly
val validatedProduct = product.validate()

Fitur Lanjutan

Konfigurasi Proxy

Konfigurasikan pengaturan proxy:

import java.net.InetSocketAddress
import java.net.Proxy

val client = DodoPaymentsOkHttpClient.builder()
    .fromEnv()
    .proxy(
        Proxy(
            Proxy.Type.HTTP,
            InetSocketAddress("proxy.example.com", 8080)
        )
    )
    .build()

Konfigurasi Sementara

Ubah konfigurasi client untuk sementara:

val customClient = client.withOptions {
    it.baseUrl("https://example.com")
    it.maxRetries(5)
}

Integrasi Ktor

Integrasikan dengan aplikasi server Ktor:

import io.ktor.server.application.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun Application.configureRouting() {
    val client = DodoPaymentsOkHttpClient.builder()
        .bearerToken(environment.config.property("dodo.apiKey").getString())
        .build()
    
    routing {
        post("/create-checkout") {
            try {
                val request = call.receive<CheckoutRequest>()
                val session = client.checkoutSessions().create(params)
                call.respond(mapOf("checkout_url" to session.checkoutUrl()))
            } catch (e: DodoPaymentsServiceException) {
                call.respond(HttpStatusCode.BadRequest, mapOf("error" to e.message))
            }
        }
    }
}

Resources

GitHub Repository

Lihat source code dan berkontribusi

API Reference

Dokumentasi API lengkap

Discord Community

Dapatkan bantuan dan terhubung dengan developer

Report Issues

Laporkan bug atau ajukan fitur

Dukungan

Perlu bantuan dengan Kotlin SDK?

Discord: Bergabunglah dengan server komunitas kami untuk mendapatkan dukungan secara real-time
Email: Hubungi kami di support@dodopayments.com
GitHub: Buka issue di repository

Berkontribusi

Kami menyambut kontribusi! Lihat panduan kontribusi untuk memulai.

​Instalasi

​Gradle (Kotlin DSL)

​Maven

​Mulai Cepat

​Fitur Utama

Coroutines

Null Safety

Extension Functions

Data Classes

​Konfigurasi

​Dari Environment Variables

​Konfigurasi Manual

​Test Mode

​Timeout dan Retry

​Operasi Umum

​Buat Checkout Session

​Buat Product

​Aktifkan License Key

​Tangani Subscription

​Penagihan Berbasis Penggunaan

​Mencatat Event Penggunaan

​Operasi Asinkron

​Async Client

​Penanganan Error

​Functional Error Handling

​Integrasi Android

​Validasi Response

​Fitur Lanjutan

​Konfigurasi Proxy

​Konfigurasi Sementara

​Integrasi Ktor

​Resources

GitHub Repository

API Reference

Discord Community

Report Issues

​Dukungan

​Berkontribusi

Instalasi

Gradle (Kotlin DSL)

Maven

Mulai Cepat

Fitur Utama

Konfigurasi

Dari Environment Variables

Konfigurasi Manual

Test Mode

Timeout dan Retry

Operasi Umum

Buat Checkout Session

Buat Product

Aktifkan License Key

Tangani Subscription

Penagihan Berbasis Penggunaan

Mencatat Event Penggunaan

Operasi Asinkron

Async Client

Penanganan Error

Functional Error Handling

Integrasi Android

Validasi Response

Fitur Lanjutan

Konfigurasi Proxy

Konfigurasi Sementara

Integrasi Ktor

Resources

Dukungan

Berkontribusi