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

Maven

Agrega la dependencia a tu pom.xml:

pom.xml

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

Siempre usa la última versión del SDK para acceder a las nuevas características de Dodo Payments. Consulta Maven Central para la última versión.

El SDK requiere Kotlin 1.6 o superior 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.CheckoutSessionRequest
import com.dodopayments.api.models.checkoutsessions.CheckoutSessionResponse

// 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(CheckoutSessionRequest.ProductCart.builder()
        .productId("product_id")
        .quantity(1)
        .build())
    .build()
    
val checkoutSessionResponse: CheckoutSessionResponse = client.checkoutSessions().create(params)
println(checkoutSessionResponse.sessionId())

Siempre almacena tus claves API de forma segura utilizando variables de entorno o configuración encriptada. Nunca las comites en el control de versiones.

Características Principales

Corutinas

Soporte completo para corutinas de Kotlin para operaciones asíncronas

Seguridad contra Nulos

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

Funciones de Extensión

Extensiones idiomáticas de Kotlin para una funcionalidad mejorada

Clases de Datos

Clases de datos seguras en tipo con soporte para 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(CheckoutSessionRequest.ProductCart.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

Usa Result para el manejo de errores funcional:

fun safeCreatePayment(client: DodoPaymentsClient): Result<Payment> = runCatching {
    client.payments().create(params)
}

// Usage
safe CreatePayment(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 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

Repositorio de GitHub

Ver el código fuente y contribuir

Referencia de API

Documentación completa de la API

Comunidad de Discord

Obtén ayuda y conéctate con desarrolladores

Reportar Problemas

Reporta errores o solicita características

Soporte

¿Necesitas ayuda con el SDK de Kotlin?

Discord: Únete a nuestro servidor comunitario para soporte en tiempo real
Email: Contáctanos en [email protected]
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

Corutinas

Seguridad contra Nulos

Funciones de Extensión

Clases de Datos

​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

Repositorio de GitHub

Referencia de API

Comunidad de Discord

Reportar Problemas

​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