Kotlin - Dodo Payments Documentation

Das Kotlin SDK bietet bequemen Zugriff auf die Dodo Payments REST API aus in Kotlin geschriebenen Anwendungen. Es bietet nullable Werte, Sequence, suspend-Funktionen und andere Kotlin-spezifische Funktionen für eine ergonomische Nutzung.

Installation

Gradle (Kotlin DSL)

Fügen Sie die Abhängigkeit zu Ihrem build.gradle.kts hinzu:

build.gradle.kts

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

Maven

Fügen Sie die Abhängigkeit zu Ihrem pom.xml hinzu:

pom.xml

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

Verwenden Sie immer die neueste SDK-Version, um auf die aktuellsten Dodo Payments-Funktionen zuzugreifen. Prüfen Sie Maven Central auf die neueste Version.

Das SDK benötigt Java 8 oder höher und ist sowohl mit der JVM als auch mit Android-Plattformen kompatibel.

Schnellstart

Initialisieren Sie den Client und erstellen Sie eine Checkout-Sitzung:

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

Speichern Sie Ihre API-Schlüssel stets sicher, z. B. über Umgebungsvariablen oder verschlüsselte Konfigurationen. Committen Sie sie niemals in Versionskontrollsysteme.

Kernfunktionen

Coroutines

Vollständige Unterstützung für Kotlin-Coroutinen für asynchrone Vorgänge

Null Safety

Nutzen Sie Kotlins Nullsicherheit für eine robuste Fehlerbehandlung

Extension Functions

Idiomatische Kotlin-Erweiterungen für erweiterte Funktionalität

Data Classes

Typensichere Datenklassen mit Unterstützung für Kopieren und Destrukturierung

Konfiguration

Aus Umgebungsvariablen

Initialisieren Sie aus Umgebungsvariablen oder Systemeigenschaften:

val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv()

Manuelle Konfiguration

Konfigurieren Sie manuell mit allen Optionen:

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

Testmodus

Für die Umgebung Test Mode konfigurieren:

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

Timeouts und Wiederholungen

Global oder pro Anfrage konfigurieren:

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

Häufige Operationen

Erstellen einer Checkout-Sitzung

Generieren Sie eine Checkout-Sitzung:

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

Erstellen eines Produkts

Erstellen Sie Produkte mit detaillierter Konfiguration:

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

Lizenzschlüssel aktivieren

Aktivieren Sie Lizenzschlüssel für Kunden:

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

Nutzungsbasierte Abrechnung

Nutzungsereignisse aufzeichnen

POST /subscriptions (die subscriptions.create-Methode des SDK) ist veraltet. Sie funktioniert weiterhin für bestehende Integrationen, aber neue Integrationen sollten Abonnements über eine Checkout Session erstellen.

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 erfordert mindestens einen zweistelligen ISO- code country. Verwende AttachExistingCustomer, um einen bestehenden Kunden zu verknüpfen, oder NewCustomer, um einen neuen Kunden zu erstellen. productPrice wird in der kleinsten Währungseinheit angegeben.

Nutzungsbasierte Abrechnung

Nutzungsereignisse erfassen

Nutzung für Meter erfassen:

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

Asynchrone Vorgänge

Asynchroner Client

Verwende den asynchronen Client für coroutine-basierte Vorgänge:

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

Fehlerbehandlung

Behandle Fehler mit der Exception-Behandlung von 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}")
}

Funktionale Fehlerbehandlung

Verwende Result für die funktionale Fehlerbehandlung:

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

Verwende Kotlin’s runCatching für einen stärker funktionalen Ansatz zur Fehlerbehandlung mit Result-Typen.

Android-Integration

Für die Verwendung mit Android-Anwendungen:

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

Antwortvalidierung

Aktiviere die Antwortvalidierung:

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

Erweiterte Funktionen

Proxy-Konfiguration

Konfiguriere die Proxy-Einstellungen:

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

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

Temporäre Konfiguration

Ändere die Client-Konfiguration vorübergehend:

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

Ktor-Integration

Integriere den Client in Ktor-Serveranwendungen:

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

Ressourcen

GitHub Repository

Quellcode anzeigen und beitragen

API Reference

Vollständige API-Dokumentation

Discord Community

Hilfe erhalten und mit Entwicklern austauschen

Report Issues

Fehler melden oder Funktionen anfordern

Support

Benötigst du Hilfe mit dem Kotlin SDK?

Discord: Tritt unserem Community-Server bei, um Support in Echtzeit zu erhalten
E-Mail: Kontaktiere uns unter support@dodopayments.com
GitHub: Erstelle ein Issue im Repository

Mitwirken

Wir freuen uns über Beiträge! Lies die Richtlinien zum Mitwirken, um loszulegen.

​Installation

​Gradle (Kotlin DSL)

​Maven

​Schnellstart

​Kernfunktionen

Coroutines

Null Safety

Extension Functions

Data Classes

​Konfiguration

​Aus Umgebungsvariablen

​Manuelle Konfiguration

​Testmodus

​Timeouts und Wiederholungen

​Häufige Operationen

​Erstellen einer Checkout-Sitzung

​Erstellen eines Produkts

​Lizenzschlüssel aktivieren

​Nutzungsbasierte Abrechnung

​Nutzungsereignisse aufzeichnen

​Nutzungsbasierte Abrechnung

​Nutzungsereignisse erfassen

​Asynchrone Vorgänge

​Asynchroner Client

​Fehlerbehandlung

​Funktionale Fehlerbehandlung

​Android-Integration

​Antwortvalidierung

​Erweiterte Funktionen

​Proxy-Konfiguration

​Temporäre Konfiguration

​Ktor-Integration

​Ressourcen

GitHub Repository

API Reference

Discord Community

Report Issues

​Support

​Mitwirken

Installation

Gradle (Kotlin DSL)

Maven

Schnellstart

Kernfunktionen

Konfiguration

Aus Umgebungsvariablen

Manuelle Konfiguration

Testmodus

Timeouts und Wiederholungen

Häufige Operationen

Erstellen einer Checkout-Sitzung

Erstellen eines Produkts

Lizenzschlüssel aktivieren

Nutzungsbasierte Abrechnung

Nutzungsereignisse aufzeichnen

Nutzungsbasierte Abrechnung

Nutzungsereignisse erfassen

Asynchrone Vorgänge

Asynchroner Client

Fehlerbehandlung

Funktionale Fehlerbehandlung

Android-Integration

Antwortvalidierung

Erweiterte Funktionen

Proxy-Konfiguration

Temporäre Konfiguration

Ktor-Integration

Ressourcen

Support

Mitwirken