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

Maven

Agrega la dependencia a tu pom.xml:

pom.xml

<dependency>
  <groupId>com.dodopayments.api</groupId>
  <artifactId>dodo-payments-kotlin</artifactId>
  <version>1.86.3</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 para el entorno de prueba/sandbox:

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

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

Crear un Producto

Crea productos con configuración detallada:

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

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

Facturación Basada en Uso

Registrar Eventos de Uso

Rastrea el uso para medidores:

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

Operaciones Asíncronas

Cliente Asíncrono

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

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

Manejo de Errores

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

Manejo de Errores Funcional

Utiliza Result para el manejo funcional de errores:

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 de Kotlin para un enfoque más funcional al manejo de errores con tipos Result.

Integración con Android

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

Validación de Respuestas

Habilita la validación de respuestas:

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

Características Avanzadas

Configuración de Proxy

Configura la configuración 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 la configuración del cliente temporalmente:

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

Recursos

GitHub Repository

Ver el código fuente y contribuir

API Reference

Documentación completa de la API

Discord Community

Obtén ayuda y conecta con desarrolladores

Report Issues

Reporta errores o solicita funciones

Soporte

¿Necesitas ayuda con el SDK de Kotlin?

Discord: Únete a nuestro servidor comunitario para soporte en tiempo real
Email: Contáctanos en support@dodopayments.com
GitHub: Abre un problema en el repositorio

Contribuyendo

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

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

​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

​Facturación Basada en Uso

​Registrar Eventos de Uso

​Operaciones Asíncronas

​Cliente Asíncrono

​Manejo de Errores

​Manejo de Errores Funcional

​Integración con Android

​Validación de Respuestas

​Características Avanzadas

​Configuración de Proxy

​Configuración Temporal

​Integración con Ktor

​Recursos

GitHub Repository

API Reference

Discord Community

Report Issues

​Soporte

​Contribuyendo

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

Facturación Basada en Uso

Registrar Eventos de Uso

Operaciones Asíncronas

Cliente Asíncrono

Manejo de Errores

Manejo de Errores Funcional

Integración con Android

Validación de Respuestas

Características Avanzadas

Configuración de Proxy

Configuración Temporal

Integración con Ktor

Recursos

Soporte

Contribuyendo