Kotlin - Dodo Payments Documentation

Le SDK Kotlin fournit un accès pratique à l’API REST de Dodo Payments depuis des applications écrites en Kotlin. Il propose des valeurs nullables, des séquences, des fonctions suspendues et d’autres fonctionnalités spécifiques à Kotlin pour une utilisation ergonomique.

Installation

Gradle (Kotlin DSL)

Ajoutez la dépendance à votre build.gradle.kts:

build.gradle.kts

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

Maven

Ajoutez la dépendance à votre pom.xml:

pom.xml

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

Utilisez toujours la dernière version du SDK pour accéder aux fonctionnalités les plus récentes de Dodo Payments. Consultez Maven Central pour connaître la version la plus récente.

Le SDK nécessite Java 8 ou une version ultérieure et est compatible avec les plateformes JVM et Android.

Démarrage rapide

Initialisez le client et créez une session de paiement :

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

Stockez toujours vos clés API de manière sécurisée en utilisant des variables d’environnement ou une configuration chiffrée. Ne les validez jamais dans le contrôle de version.

Fonctionnalités principales

Coroutines

Prise en charge complète des coroutines Kotlin pour les opérations asynchrones

Null Safety

Profitez de la sécurité contre les valeurs nulles de Kotlin pour une gestion des erreurs robuste

Extension Functions

Extensions idiomatiques Kotlin pour une fonctionnalité améliorée

Data Classes

Classes de données types-sûrs avec prise en charge de copy et destructuration

Configuration

À partir des variables d’environnement

Initialisez à partir des variables d’environnement ou des propriétés système :

val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv()

Configuration manuelle

Configurez manuellement avec toutes les options :

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

Mode test

Configurez l’environnement Test Mode :

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

Timeouts et réessais

Configurez globalement ou par requête :

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

Opérations courantes

Créer une session de paiement

Générez une session de paiement :

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

Créer un produit

Créez des produits avec une configuration détaillée :

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

Activer la clé de licence

Activez les clés de licence pour les clients :

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

Facturation basée sur l’utilisation

Enregistrer des événements d’utilisation

POST /subscriptions (la méthode subscriptions.create du SDK) est obsolète. Elle fonctionne toujours pour les intégrations existantes, mais les nouvelles intégrations doivent créer des abonnements via une 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 nécessite au minimum un code ISO country à deux lettres. Utilisez AttachExistingCustomer pour associer un client existant, ou NewCustomer pour en créer un. productPrice est exprimé dans la plus petite unité monétaire.

Facturation basée sur l’utilisation

Enregistrer les événements d’utilisation

Suivez l’utilisation pour les compteurs :

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

Opérations asynchrones

Client asynchrone

Utilisez le client asynchrone pour les opérations basées sur des coroutines :

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

Gestion des erreurs

Gérez les erreurs avec la gestion des exceptions de 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}")
}

Gestion fonctionnelle des erreurs

Utilisez Result pour la gestion fonctionnelle des erreurs :

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

Utilisez runCatching de Kotlin pour une approche plus fonctionnelle de la gestion des erreurs avec les types Result.

Intégration Android

Utilisez-le avec des applications 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)
            }
        }
    }
}

Validation des réponses

Activez la validation des réponses :

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

Fonctionnalités avancées

Configuration du proxy

Configurez les paramètres du 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()

Configuration temporaire

Modifiez temporairement la configuration du client :

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

Intégration Ktor

Intégrez-le à des applications serveur 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))
            }
        }
    }
}

Ressources

GitHub Repository

Consultez le code source et contribuez

API Reference

Documentation complète de l’API

Discord Community

Obtenez de l’aide et échangez avec des développeurs

Report Issues

Signalez des bugs ou demandez de nouvelles fonctionnalités

Assistance

Besoin d’aide avec le Kotlin SDK ?

Discord : Rejoignez notre serveur communautaire pour obtenir de l’assistance en temps réel
E-mail : Contactez-nous à l’adresse support@dodopayments.com
GitHub : Ouvrez un ticket dans le dépôt

Contribuer

Nous accueillons volontiers les contributions ! Consultez les instructions de contribution pour commencer.

​Installation

​Gradle (Kotlin DSL)

​Maven

​Démarrage rapide

​Fonctionnalités principales

Coroutines

Null Safety

Extension Functions

Data Classes

​Configuration

​À partir des variables d’environnement

​Configuration manuelle

​Mode test

​Timeouts et réessais

​Opérations courantes

​Créer une session de paiement

​Créer un produit

​Activer la clé de licence

​Facturation basée sur l’utilisation

​Enregistrer des événements d’utilisation

​Facturation basée sur l’utilisation

​Enregistrer les événements d’utilisation

​Opérations asynchrones

​Client asynchrone

​Gestion des erreurs

​Gestion fonctionnelle des erreurs

​Intégration Android

​Validation des réponses

​Fonctionnalités avancées

​Configuration du proxy

​Configuration temporaire

​Intégration Ktor

​Ressources

GitHub Repository

API Reference

Discord Community

Report Issues

​Assistance

​Contribuer

Installation

Gradle (Kotlin DSL)

Maven

Démarrage rapide

Fonctionnalités principales

Configuration

À partir des variables d’environnement

Configuration manuelle

Mode test

Timeouts et réessais

Opérations courantes

Créer une session de paiement

Créer un produit

Activer la clé de licence

Facturation basée sur l’utilisation

Enregistrer des événements d’utilisation

Facturation basée sur l’utilisation

Enregistrer les événements d’utilisation

Opérations asynchrones

Client asynchrone

Gestion des erreurs

Gestion fonctionnelle des erreurs

Intégration Android

Validation des réponses

Fonctionnalités avancées

Configuration du proxy

Configuration temporaire

Intégration Ktor

Ressources

Assistance

Contribuer