Kotlin - Dodo Payments Documentation

Le SDK Kotlin permet aux applications Kotlin d’accéder à l’API REST de Dodo Payments avec des types. Il utilise partout les types Kotlin : des valeurs nullable pour les champs susceptibles d’être absents, Sequence pour parcourir les résultats et des fonctions suspend pour les appels asynchrones.

Installation

Gradle (Kotlin DSL)

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

build.gradle.kts

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

Maven

Ajoutez la dépendance à votre pom.xml:

pom.xml

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

Les versions du SDK ajoutent la prise en charge des modifications de l’API. Pour trouver la version la plus récente, consultez Maven Central.

Le SDK nécessite Java 8 ou une version ultérieure. Il s’exécute sur la JVM et Android, et inclut des règles de conservation pour ProGuard et R8.

Démarrage rapide

Créez un client, puis 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.CheckoutSessionRequest
import com.dodopayments.api.models.checkoutsessions.CheckoutSessionResponse
import com.dodopayments.api.models.checkoutsessions.ProductItemReq

// Configure using environment variables (DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_WEBHOOK_KEY, DODO_PAYMENTS_BASE_URL)
// Or system properties (dodopayments.apiKey, dodopayments.webhookKey, dodopayments.baseUrl)
val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv()

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

fromEnv() se connecte au mode live, sauf si DODO_PAYMENTS_BASE_URL ou dodopayments.baseUrl indique le contraire. Pour utiliser le mode test, consultez Mode test. Une clé API de test fonctionne uniquement en mode test.

Conservez les clés API dans des variables d’environnement ou un gestionnaire de secrets. Ne les validez jamais dans le contrôle de version.

Fonctionnalités principales

Coroutines

Les méthodes du client asynchrone sont des fonctions suspend que vous appelez depuis une coroutine.

Null Safety

Les champs susceptibles d’être absents sont des types nullable, et non Optional.

Sequences

Sur le client synchrone, autoPager() renvoie un Sequence qui récupère davantage de pages au fil de l’itération. Sur le client asynchrone, il renvoie un Flow.

Immutable Models

Les classes de modèle sont immuables, et toBuilder() renvoie un builder pour une copie modifiée.

Configuration

Depuis des variables d’environnement

fromEnv() lit vos paramètres depuis les variables d’environnement ou les propriétés système. Les propriétés système sont prioritaires :

val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv()

La clé API provient de DODO_PAYMENTS_API_KEY ou dodopayments.apiKey. Le secret de signature du webhook provient de DODO_PAYMENTS_WEBHOOK_KEY ou dodopayments.webhookKey, et l’URL de base de DODO_PAYMENTS_BASE_URL ou dodopayments.baseUrl. Créez un seul client et réutilisez-le, car chaque client possède son propre pool de connexions et ses propres pools de threads. Pour vérifier un webhook, transmettez le corps brut de la requête et les en-têtes à client.webhooks().unwrap(UnwrapWebhookParams.builder().body(rawBody).headers(headers).build()), où headers est un com.dodopayments.api.core.http.Headers. La signature est vérifiée avec votre clé webhook, puis l’événement analysé est renvoyé ; sinon, DodoPaymentsWebhookException est levée. Sans en-têtes, unwrap ne vérifie pas la signature. client.webhooks().unsafeUnwrap(rawBody) analyse le corps sans le vérifier ; utilisez-le donc uniquement pour les tests. Consultez Webhooks.

Configuration manuelle

Définissez chaque option sur le builder :

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

Pour utiliser le mode test (https://test.dodopayments.com), appelez testMode() sur le builder :

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

Délais d’expiration et nouvelles tentatives

Par défaut, le client effectue deux nouvelles tentatives et expire après 1 minute. Il réessaie en cas d’erreurs de connexion et de réponses avec le statut 408, 409, 429 ou 500 et supérieur, avec un backoff exponentiel. Définissez les valeurs par défaut sur le client ou transmettez RequestOptions à un appel donné :

import com.dodopayments.api.core.RequestOptions
import java.time.Duration

// 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

Les exemples de cette section utilisent le client de Démarrage rapide.

Créer une session de paiement

Créez une session de paiement, puis redirigez le client vers l’URL de paiement renvoyée :

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

checkoutUrl() renvoie un String? nullable. Chaque URL de paiement est utilisable une seule fois et expire après 24 heures. Pour connaître toutes les options de session, consultez Sessions de paiement.

Créer un produit

Créez un produit d’abonnement mensuel au prix de $29.99 :

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.subscriptions.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
            .discountBps(0)
            .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()}")

price est exprimé dans l’unité monétaire minimale. discountBps définit la remise en points de base et remplace le champ obsolète discount.

Activer une clé de licence

Activez une clé de licence pour un appareil ou une installation. Si la clé a atteint sa limite d’activations, l’API renvoie 422 et le SDK lève UnprocessableEntityException. Une clé inactive renvoie 403 (PermissionDeniedException), tandis qu’une clé inconnue renvoie 404 (NotFoundException) :

import com.dodopayments.api.errors.UnprocessableEntityException
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}")
}

Gérer les abonnements

Créez un abonnement, puis facturez-le s’il s’agit d’un abonnement à la demande.

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 les abonnements via une session de paiement.

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 uniquement country, un code pays ISO à deux lettres. Utilisez AttachExistingCustomer pour associer un client existant ou NewCustomer pour en créer un. charge est destiné aux abonnements à la demande, et productPrice est exprimé dans l’unité monétaire minimale.

Facturation à l’usage

Enregistrer des événements d’utilisation

Envoyez un événement d’utilisation pour un client. Les compteurs qui suivent eventName l’agrègent :

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

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

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

eventId est la clé d’idempotence ; attribuez donc une valeur unique à chaque événement. Une requête accepte jusqu’à 1 000 événements.

Opérations asynchrones

Client asynchrone

Le client asynchrone possède les mêmes méthodes que le client synchrone, mais la plupart sont des fonctions suspend. Appelez-les depuis une 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("cus_123")
    println("Customer email: ${customer.email()}")
}

Vous pouvez également appeler client.async() sur un client synchrone pour obtenir sa version asynchrone.

Gestion des erreurs

Pour un statut d’erreur, le SDK lève une sous-classe de DodoPaymentsServiceException, qui possède statusCode(), headers() et body(). Les sous-classes sont BadRequestException (400), UnauthorizedException (401), PermissionDeniedException (403), NotFoundException (404), UnprocessableEntityException (422), RateLimitException (429), InternalServerException (5xx) et UnexpectedStatusCodeException pour les autres statuts, comme 409 :

import com.dodopayments.api.errors.*

try {
    // Note: POST /payments is deprecated — prefer checkout sessions for new
    // integrations. Shown here only to illustrate error handling.
    // paymentParams is a PaymentCreateParams with billing, customer, and productCart.
    val payment = client.payments().create(paymentParams)
    println("Success: ${payment.paymentId()}")
} catch (e: UnauthorizedException) {
    println("Authentication failed: ${e.message}")
} catch (e: BadRequestException) {
    println("Invalid request: ${e.message}")
    println("Response body: ${e.body()}")
} catch (e: RateLimitException) {
    println("Rate limit exceeded, retry after: ${e.headers().values("retry-after")}")
} catch (e: DodoPaymentsServiceException) {
    println("API error: ${e.statusCode()} - ${e.message}")
}

Les défaillances réseau lèvent DodoPaymentsIoException, et les réponses que le SDK ne peut pas interpréter lèvent DodoPaymentsInvalidDataException. Toutes les exceptions du SDK étendent DodoPaymentsException.

Gestion fonctionnelle des erreurs

Utilisez Result pour la gestion fonctionnelle des erreurs :

import com.dodopayments.api.client.DodoPaymentsClient
import com.dodopayments.api.models.payments.PaymentCreateResponse

fun safeCreatePayment(client: DodoPaymentsClient): Result<PaymentCreateResponse> = runCatching {
    // Note: POST /payments is deprecated — prefer checkout sessions for new integrations
    // paymentParams is a PaymentCreateParams with billing, customer, and productCart.
    client.payments().create(paymentParams)
}

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

runCatching intercepte toutes les exceptions, y compris celles du SDK, et les renvoie sous la forme d’un Result en échec.

Intégration Android

Le Kotlin SDK est un SDK serveur. Il s’authentifie avec votre clé API secrète, et toute personne possédant votre APK peut extraire une clé qui y est compilée ; ne l’utilisez donc jamais dans une application Android. Pour accepter des paiements dans une application Android :

Sur votre serveur, créez la session de checkout avec ce SDK (voir Intégration Ktor) et renvoyez sa checkout_url.
Dans l’application, récupérez cette checkout_url depuis votre serveur et ouvrez-la avec l’Android SDK, qui ne contient aucune clé API.

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.launch

class PaymentViewModel(private val api: YourBackendApi) : ViewModel() {
    fun createCheckout(productId: String) {
        viewModelScope.launch {
            // Your backend creates the session with the Kotlin SDK and returns checkout_url.
            // YourBackendApi and openCheckout are your app's own code; openCheckout
            // passes the URL to DodoCheckout from the Android SDK.
            val checkoutUrl = api.createCheckoutSession(productId).checkoutUrl
            openCheckout(checkoutUrl)
        }
    }
}

Validation de la réponse

Par défaut, le SDK lève DodoPaymentsInvalidDataException uniquement lorsque vous lisez une propriété dont le type est inattendu. Pour vérifier l’intégralité de la réponse au préalable, activez la validation pour une requête ou appelez validate() sur une réponse :

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

Pour envoyer des requêtes via un proxy, transmettez un java.net.Proxy au builder :

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

withOptions renvoie un client avec des paramètres modifiés qui partage les pools de connexions et de threads du client d’origine. Le client d’origine reste inchangé :

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

Intégration Ktor

Créez le client une seule fois et appelez-le depuis une route :

import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient
import com.dodopayments.api.errors.DodoPaymentsServiceException
import com.dodopayments.api.models.checkoutsessions.CheckoutSessionRequest
import com.dodopayments.api.models.checkoutsessions.ProductItemReq
import io.ktor.http.HttpStatusCode
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 {
                // CheckoutRequest is your own @Serializable request class with a productId field
                val request = call.receive<CheckoutRequest>()
                val params = CheckoutSessionRequest.builder()
                    .addProductCart(ProductItemReq.builder().productId(request.productId).quantity(1).build())
                    .build()
                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

Code source, versions et liste complète des méthodes.

API Reference

Chaque endpoint, paramètre et réponse.

Discord Community

Posez vos questions et échangez avec d’autres développeurs.

Report Issues

Signalez des bugs ou demandez des fonctionnalités.

Assistance

Pour obtenir de l’aide concernant le Kotlin SDK :

Discord : Rejoignez le serveur de la communauté pour obtenir de l’aide en temps réel.
Email : Contactez support@dodopayments.com.
GitHub : Ouvrez une issue dans le repository.

Contribuer

Pour contribuer, consultez les directives de contribution.

​Installation

​Gradle (Kotlin DSL)

​Maven

​Démarrage rapide

​Fonctionnalités principales

Coroutines

Null Safety

Sequences

Immutable Models

​Configuration

​Depuis des variables d’environnement

​Configuration manuelle

​Mode test

​Délais d’expiration et nouvelles tentatives

​Opérations courantes

​Créer une session de paiement

​Créer un produit

​Activer une clé de licence

​Gérer les abonnements

​Facturation à l’usage

​Enregistrer des événements d’utilisation

​Opérations asynchrones

​Client asynchrone

​Gestion des erreurs

​Gestion fonctionnelle des erreurs

​Intégration Android

​Validation de la réponse

​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

Depuis des variables d’environnement

Configuration manuelle

Mode test

Délais d’expiration et nouvelles tentatives

Opérations courantes

Créer une session de paiement

Créer un produit

Activer une clé de licence

Gérer les abonnements

Facturation à l’usage

Enregistrer des événements d’utilisation

Opérations asynchrones

Client asynchrone

Gestion des erreurs

Gestion fonctionnelle des erreurs

Intégration Android

Validation de la réponse

Fonctionnalités avancées

Configuration du proxy

Configuration temporaire

Intégration Ktor

Ressources

Assistance

Contribuer