Kotlin - Dodo Payments Documentation

El SDK de Kotlin proporciona acceso conveniente a la API REST de Dodo Payments desde aplicaciones escritas en Kotlin. Presenta valores anulables, Sequence, funciones suspendidas y otras características específicas de Kotlin para un uso ergonómico.

Instalación

Gradle (Kotlin DSL)

Agrega la dependencia a tu build.gradle.kts:

build.gradle.kts

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

Maven

Agrega la dependencia a tu pom.xml:

pom.xml

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

Utiliza siempre la versión más reciente del SDK para acceder a las funciones más nuevas de Dodo Payments. Consulta Maven Central para conocer la versión más reciente.

El SDK requiere Java 8 o posterior y es compatible con plataformas JVM y Android.

Inicio Rápido

Inicializa el cliente y crea una sesión de pago:

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

Siempre almacena tus claves de API de forma segura usando variables de entorno o configuración cifrada. Nunca las subas al control de versiones.

Características Principales

Coroutines

Soporte completo para corrutinas de Kotlin en operaciones asincrónicas

Null Safety

Aprovecha la seguridad ante nulos de Kotlin para un manejo de errores robusto

Extension Functions

Extensiones idiomáticas de Kotlin para funcionalidad mejorada

Data Classes

Clases de datos con tipado seguro que admiten copia y desestructuración

Configuración

Desde Variables de Entorno

Inicializa desde variables de entorno o propiedades del sistema:

val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv()

Configuración Manual

Configura manualmente con todas las opciones:

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

Modo de Prueba

Configura el entorno de Test Mode:

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

Timeouts y Reintentos

Configura globalmente o por solicitud:

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

Operaciones Comunes

Crear una Sesión de Pago

Genera una sesión de pago:

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

Crear un Producto

Crea productos con configuración detallada:

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

Activar Clave de Licencia

Activa claves de licencia para clientes:

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

Manejar Suscripciones

Crear y gestionar suscripciones recurrentes:

POST /subscriptions (el método subscriptions.create del SDK) está obsoleto. Sigue funcionando para las integraciones existentes, pero las nuevas integraciones deben crear suscripciones mediante 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 requiere como mínimo un código ISO country de dos letras. Usa AttachExistingCustomer para asociar un cliente existente o NewCustomer para crear uno. productPrice se expresa en la denominación monetaria más pequeña.

Facturación basada en el uso

Registrar eventos de uso

Registra el uso de los medidores:

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

Operaciones asíncronas

Cliente asíncrono

Usa el cliente asíncrono para operaciones basadas en corrutinas:

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

Gestión de errores

Gestiona los errores con el manejo de excepciones 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}")
}

Gestión funcional de errores

Usa Result para la gestión funcional de errores:

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 de Kotlin para adoptar un enfoque más funcional en la gestión de errores con tipos Result.

Integración con Android

Úsalo con aplicaciones de 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)
            }
        }
    }
}

Validación de respuestas

Activa la validación de respuestas:

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

Funciones avanzadas

Configuración del proxy

Configura los ajustes 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()

Configuración temporal

Modifica temporalmente la configuración del cliente:

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

Integración con Ktor

Integra con aplicaciones de servidor 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))
            }
        }
    }
}

Recursos

GitHub Repository

Consulta el código fuente y contribuye

API Reference

Documentación completa de la API

Discord Community

Obtén ayuda y conéctate con desarrolladores

Report Issues

Informa de errores o solicita funciones

Soporte

¿Necesitas ayuda con el Kotlin SDK?

Discord: Únete a nuestro servidor de la comunidad para recibir asistencia en tiempo real
Correo electrónico: Contáctanos en support@dodopayments.com
GitHub: Abre una incidencia en el repositorio

Contribuciones

¡Damos la bienvenida a las contribuciones! Consulta las directrices de contribución para comenzar.

​Instalación

​Gradle (Kotlin DSL)

​Maven

​Inicio Rápido

​Características Principales

Coroutines

Null Safety

Extension Functions

Data Classes

​Configuración

​Desde Variables de Entorno

​Configuración Manual

​Modo de Prueba

​Timeouts y Reintentos

​Operaciones Comunes

​Crear una Sesión de Pago

​Crear un Producto

​Activar Clave de Licencia

​Manejar Suscripciones

​Facturación basada en el uso

​Registrar eventos de uso

​Operaciones asíncronas

​Cliente asíncrono

​Gestión de errores

​Gestión funcional de errores

​Integración con Android

​Validación de respuestas

​Funciones avanzadas

​Configuración del proxy

​Configuración temporal

​Integración con Ktor

​Recursos

GitHub Repository

API Reference

Discord Community

Report Issues

​Soporte

​Contribuciones

Instalación

Gradle (Kotlin DSL)

Maven

Inicio Rápido

Características Principales

Configuración

Desde Variables de Entorno

Configuración Manual

Modo de Prueba

Timeouts y Reintentos

Operaciones Comunes

Crear una Sesión de Pago

Crear un Producto

Activar Clave de Licencia

Manejar Suscripciones

Facturación basada en el uso

Registrar eventos de uso

Operaciones asíncronas

Cliente asíncrono

Gestión de errores

Gestión funcional de errores

Integración con Android

Validación de respuestas

Funciones avanzadas

Configuración del proxy

Configuración temporal

Integración con Ktor

Recursos

Soporte

Contribuciones