Kotlin - Dodo Payments Documentation

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 Test Mode:

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(
    "pdt_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("pdt_123")
        .quantity(1)
        .build())
    .returnUrl("https://yourdomain.com/return")
    .build()

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

Crea un Prodotto

Crea prodotti con configurazione dettagliata:

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

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

Gestire gli abbonamenti

Crea e gestisci abbonamenti ricorrenti:

POST /subscriptions (il metodo subscriptions.create dell’SDK) è deprecato. Continua a funzionare per le integrazioni esistenti, ma per le nuove integrazioni è consigliabile creare le sottoscrizioni tramite una 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 richiede almeno un codice country ISO di due lettere. Usa AttachExistingCustomer per associare un cliente esistente oppure NewCustomer per crearne uno. productPrice è espresso nella denominazione più bassa della valuta.

Fatturazione basata sull’utilizzo

Registra gli eventi di utilizzo

Monitora l’utilizzo per i contatori:

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

Operazioni asincrone

Client asincrono

Usa il client asincrono per le 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.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}")
}

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.paymentId()}") }
    .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 le 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.checkoutUrl())
            } catch (e: Exception) {
                handleError(e)
            }
        }
    }
}

Convalida delle risposte

Abilita la convalida delle risposte:

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

Funzionalità avanzate

Configurazione del 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 le 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.checkoutUrl()))
            } catch (e: DodoPaymentsServiceException) {
                call.respond(HttpStatusCode.BadRequest, mapOf("error" to e.message))
            }
        }
    }
}

Risorse

GitHub Repository

Visualizza il codice sorgente e contribuisci

API Reference

Documentazione completa dell’API

Discord Community

Ottieni assistenza e mettiti in contatto con gli sviluppatori

Report Issues

Segnala bug o richiedi funzionalità

Supporto

Hai bisogno di aiuto con l’SDK Kotlin?

Discord: Unisciti al nostro server della community per ricevere supporto in tempo reale
Email: Contattaci all’indirizzo support@dodopayments.com
GitHub: Apri una segnalazione nel repository

Contributi

Accogliamo con piacere i contributi! Consulta le linee guida per i contributi per iniziare.

​Installazione

​Gradle (Kotlin DSL)

​Maven

​Inizio Veloce

​Funzionalità Principali

Coroutines

Null Safety

Extension Functions

Data Classes

​Configurazione

​Da Variabili d’Ambiente

​Configurazione Manuale

​Modalità Test

​Timeouts e Retry

​Operazioni Comuni

​Crea una Sessione di Checkout

​Crea un Prodotto

​Attiva la Chiave di Licenza

​Gestire gli abbonamenti

​Fatturazione basata sull’utilizzo

​Registra gli eventi di utilizzo

​Operazioni asincrone

​Client asincrono

​Gestione degli errori

​Gestione funzionale degli errori

​Integrazione Android

​Convalida delle risposte

​Funzionalità avanzate

​Configurazione del proxy

​Configurazione temporanea

​Integrazione Ktor

​Risorse

GitHub Repository

API Reference

Discord Community

Report Issues

​Supporto

​Contributi

Installazione

Gradle (Kotlin DSL)

Maven

Inizio Veloce

Funzionalità Principali

Configurazione

Da Variabili d’Ambiente

Configurazione Manuale

Modalità Test

Timeouts e Retry

Operazioni Comuni

Crea una Sessione di Checkout

Crea un Prodotto

Attiva la Chiave di Licenza

Gestire gli abbonamenti

Fatturazione basata sull’utilizzo

Registra gli eventi di utilizzo

Operazioni asincrone

Client asincrono

Gestione degli errori

Gestione funzionale degli errori

Integrazione Android

Convalida delle risposte

Funzionalità avanzate

Configurazione del proxy

Configurazione temporanea

Integrazione Ktor

Risorse

Supporto

Contributi