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

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

Manejar Suscripciones

Crear y gestionar suscripciones recurrentes:

import com.dodopayments.api.models.payments.AttachExistingCustomer
import com.dodopayments.api.models.payments.BillingAddress
import com.dodopayments.api.models.payments.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 al menos un código ISO country de dos letras. Usa AttachExistingCustomer para adjuntar un cliente existente, o NewCustomer para crear uno. productPrice se expresa en la denominación más baja de la moneda.

Facturación Basada en Uso

Registrar Eventos de Uso

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

Manejo de Errores

Gestionar 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 Funcional de Errores

Usa 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 en el manejo de errores con tipos de Result.

Integración con Android

Usar 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

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

Funcionalidades Avanzadas

Configuración de Proxy

Configurar ajustes de 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

Modificar temporalmente la configuración del cliente:

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

Integración con Ktor

Integrar 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

Ver el código fuente y contribuir

API Reference

Documentación completa de la API

Discord Community

Obtén ayuda y conéctate con desarrolladores

Report Issues

Reportar errores o solicitar funcionalidades

Soporte

¿Necesitas ayuda con el SDK de Kotlin?

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

Contribuir

¡Agradecemos 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 Uso

​Registrar Eventos de Uso

​Operaciones Asíncronas

​Cliente Asíncrono

​Manejo de Errores

​Manejo Funcional de Errores

​Integración con Android

​Validación de Respuestas

​Funcionalidades Avanzadas

​Configuración de Proxy

​Configuración Temporal

​Integración con Ktor

​Recursos

GitHub Repository

API Reference

Discord Community

Report Issues

​Soporte

​Contribuir

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 Uso

Registrar Eventos de Uso

Operaciones Asíncronas

Cliente Asíncrono

Manejo de Errores

Manejo Funcional de Errores

Integración con Android

Validación de Respuestas

Funcionalidades Avanzadas

Configuración de Proxy

Configuración Temporal

Integración con Ktor

Recursos

Soporte

Contribuir