Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt

Use this file to discover all available pages before exploring further.

Il SDK Kotlin fornisce un accesso conveniente all’API REST di Dodo Payments da applicazioni scritte in Kotlin. Presenta valori nullable, Sequence, funzioni suspend e altre funzionalità specifiche di Kotlin per un uso ergonomico.

​
Installazione

​
Gradle (Kotlin DSL)

Aggiungi la dipendenza al tuo build.gradle.kts:
build.gradle.kts
implementation("com.dodopayments.api:dodo-payments-kotlin:1.97.1")

​
Maven

Aggiungi la dipendenza al tuo pom.xml:
pom.xml
<dependency>
  <groupId>com.dodopayments.api</groupId>
  <artifactId>dodo-payments-kotlin</artifactId>
  <version>1.97.1</version>
</dependency>
Usa sempre l’ultima versione dell’SDK per accedere alle funzionalità più recenti di Dodo Payments. Controlla Maven Central per la versione più aggiornata.
L’SDK richiede Java 8 o versioni successive ed è compatibile sia con le piattaforme JVM che Android.

​
Inizio Veloce

Inizializza il client e crea una sessione di checkout: 
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())
Conserva sempre le chiavi API in modo sicuro utilizzando variabili d’ambiente o configurazioni crittografate. Non includerle mai nel controllo versione.

​
Funzionalità Principali

Coroutines

Supporto completo per le coroutine di Kotlin per operazioni asincrone

Null Safety

Sfrutta la sicurezza dei null di Kotlin per una gestione degli errori robusta

Extension Functions

Estensioni idiomatiche di Kotlin per funzionalità avanzate

Data Classes

Classi dati type-safe con supporto per copy e distrutturazione

​
Configurazione

​
Da Variabili d’Ambiente

Inizializza da variabili d’ambiente o proprietà di sistema: 
val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv()

​
Configurazione Manuale

Configura manualmente con tutte le opzioni: 
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()

​
Modalità Test

Configura per l’ambiente di test/sandbox: 
val testClient = DodoPaymentsOkHttpClient.builder()
    .fromEnv()
    .testMode()
    .build()

​
Timeouts e Retry

Configura globalmente o per richiesta: 
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(
    "prod_123",
    RequestOptions.builder()
        .timeout(Duration.ofSeconds(10))
        .build()
)

​
Operazioni Comuni

​
Crea una Sessione di Checkout

Genera una sessione di checkout: 
val params = CheckoutSessionRequest.builder()
    .addProductCart(ProductItemReq.builder()
        .productId("prod_123")
        .quantity(1)
        .build())
    .returnUrl("https://yourdomain.com/return")
    .build()

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

​
Crea un Prodotto

Crea prodotti con configurazione dettagliata: 
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

val createParams = ProductCreateParams.builder()
    .name("Premium Subscription")
    .description("Monthly subscription with all features")
    .price(
        ProductCreateParams.RecurringPrice.builder()
            .currency(Currency.USD)
            .preTaxAmount(2999) // $29.99 in cents
            .paymentFrequencyInterval(ProductCreateParams.RecurringPrice.TimeInterval.MONTH)
            .paymentFrequencyCount(1)
            .build()
    )
    .taxCategory(TaxCategory.DIGITAL_GOODS)
    .build()

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

​
Attiva la Chiave di Licenza

Attiva chiavi di licenza per i clienti: 
import com.dodopayments.api.models.licenses.LicenseActivateParams
import com.dodopayments.api.models.licenses.LicenseActivateResponse

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

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

    println("License activated successfully")
    println("Instance ID: ${activationResult.instanceId()}")
    println("Expires at: ${activationResult.expiresAt()}")
} catch (e: UnprocessableEntityException) {
    println("License activation failed: ${e.message}")
}

​
Gestire gli abbonamenti

Crea e gestisci abbonamenti ricorrenti: 
import com.dodopayments.api.models.payments.AttachExistingCustomer
import com.dodopayments.api.models.payments.BillingAddress
import com.dodopayments.api.models.payments.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 richiede almeno un codice ISO a due lettere country. Usa AttachExistingCustomer per collegare un cliente esistente o NewCustomer per crearne uno. productPrice è espresso nella denominazione di valuta più bassa.

​
Fatturazione basata sull’uso

​
Registra gli eventi di utilizzo

Traccia l’uso per i contatori: 
import com.dodopayments.api.models.usageevents.UsageEventCreateParams
import java.time.OffsetDateTime

val usageParams = UsageEventCreateParams.builder()
    .meterId("meter_123")
    .customerId("cust_456")
    .value(150)
    .timestamp(OffsetDateTime.now())
    .build()

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

​
Operazioni asincrone

​
Client asincrono

Usa il client asincrono per operazioni basate su 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()}")
}

​
Gestione degli errori

Gestisci gli errori con la gestione delle eccezioni di Kotlin: 
import com.dodopayments.api.errors.*

try {
    val payment = client.payments().create(params)
    println("Success: ${payment.id()}")
} 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}")
}

​
Gestione funzionale degli errori

Usa Result per la gestione funzionale degli errori: 
fun safeCreatePayment(client: DodoPaymentsClient): Result<Payment> = runCatching {
    client.payments().create(params)
}

// Usage
safeCreatePayment(client)
    .onSuccess { payment -> println("Created: ${payment.id()}") }
    .onFailure { error -> println("Error: ${error.message}") }
Usa runCatching di Kotlin per un approccio più funzionale alla gestione degli errori con i tipi Result.

​
Integrazione Android

Usa con applicazioni 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.url())
            } catch (e: Exception) {
                handleError(e)
            }
        }
    }
}

​
Validazione delle risposte

Abilita la validazione delle risposte: 
import com.dodopayments.api.core.RequestOptions

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

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

​
Funzionalità avanzate

​
Configurazione proxy

Configura le impostazioni del 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()

​
Configurazione temporanea

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

​
Integrazione Ktor

Integra con applicazioni 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.url()))
            } catch (e: DodoPaymentsServiceException) {
                call.respond(HttpStatusCode.BadRequest, mapOf("error" to e.message))
            }
        }
    }
}

​
Risorse

GitHub Repository

Visualizza il codice sorgente e contribuisci

API Reference

Completa la documentazione API

Discord Community

Ottieni aiuto e connettiti con gli sviluppatori

Report Issues

Segnala bug o richiedi funzionalità

​
Supporto

Hai bisogno di aiuto con il Kotlin SDK?

​
Contributi

Accogliamo con favore i contributi! Consulta le linee guida per i contributi per iniziare.
Last modified on May 14, 2026