Kotlin - Dodo Payments Documentation

O SDK Kotlin fornece acesso conveniente à API REST de pagamentos Dodo a partir de aplicações escritas em Kotlin. Ele apresenta valores anuláveis, Sequence, funções suspensas e outros recursos específicos do Kotlin para um uso ergonômico.

Instalação

Gradle (Kotlin DSL)

Adicione a dependência ao seu build.gradle.kts:

build.gradle.kts

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

Maven

Adicione a dependência ao seu pom.xml:

pom.xml

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

Sempre use a versão mais recente do SDK para acessar os recursos mais novos da Dodo Payments. Verifique Maven Central para obter a versão mais recente.

O SDK requer Java 8 ou posterior e é compatível tanto com plataformas JVM quanto Android.

Início Rápido

Inicialize o cliente e crie uma sessão de checkout:

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

Sempre armazene suas chaves de API com segurança usando variáveis de ambiente ou configuração criptografada. Nunca as envie para o controle de versão.

Recursos Principais

Coroutines

Suporte completo para corrotinas Kotlin em operações assíncronas

Null Safety

Aproveite a segurança contra nulos do Kotlin para um tratamento de erros robusto

Extension Functions

Extensões idiomáticas do Kotlin para funcionalidade aprimorada

Data Classes

Classes de dados com tipagem segura e suporte a copy e destructuring

Configuração

A partir de Variáveis de Ambiente

Inicialize a partir de variáveis de ambiente ou propriedades do sistema:

val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv()

Configuração Manual

Configure manualmente com todas as opções:

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 Teste

Configure para ambiente de teste/sandbox:

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

Timeouts e Retentativas

Configure globalmente ou por solicitação:

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

Operações Comuns

Criar uma Sessão de Checkout

Gere uma sessão de checkout:

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

Criar um Produto

Crie produtos com configuração detalhada:

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

Ativar Chave de Licença

Ative chaves de licença 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}")
}

Cobrança Baseada em Uso

Registrar Eventos de Uso

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

Operações Assíncronas

Cliente Assíncrono

Use o cliente assíncrono para operações baseadas em corrotinas:

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

Tratamento de Erros

Trate erros com o tratamento de exceções do 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}")
}

Tratamento Funcional de Erros

Use Result para um tratamento funcional de erros:

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

Use a runCatching do Kotlin para uma abordagem mais funcional no tratamento de erros com tipos Result.

Integração com Android

Use com aplicações 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)
            }
        }
    }
}

Validação de Resposta

Habilite a validação de resposta:

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

Recursos Avançados

Configuração de Proxy

Configure as configurações 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()

Configuração Temporária

Modifique a configuração do cliente temporariamente:

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

Integração com Ktor

Integre com aplicações 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

Veja o código-fonte e contribua

API Reference

Documentação completa da API

Discord Community

Obtenha ajuda e conecte-se com desenvolvedores

Report Issues

Reporte bugs ou solicite recursos

Suporte

Precisa de ajuda com o SDK Kotlin?

Discord: Junte-se ao nosso servidor da comunidade para suporte em tempo real
Email: Entre em contato conosco pelo support@dodopayments.com
GitHub: Abra um problema no repositório

Contribuindo

Agradecemos contribuições! Confira as diretrizes de contribuição para começar.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

​Instalação

​Gradle (Kotlin DSL)

​Maven

​Início Rápido

​Recursos Principais

Coroutines

Null Safety

Extension Functions

Data Classes

​Configuração

​A partir de Variáveis de Ambiente

​Configuração Manual

​Modo de Teste

​Timeouts e Retentativas

​Operações Comuns

​Criar uma Sessão de Checkout

​Criar um Produto

​Ativar Chave de Licença

​Cobrança Baseada em Uso

​Registrar Eventos de Uso

​Operações Assíncronas

​Cliente Assíncrono

​Tratamento de Erros

​Tratamento Funcional de Erros

​Integração com Android

​Validação de Resposta

​Recursos Avançados

​Configuração de Proxy

​Configuração Temporária

​Integração com Ktor

​Recursos

GitHub Repository

API Reference

Discord Community

Report Issues

​Suporte

​Contribuindo

Instalação

Gradle (Kotlin DSL)

Maven

Início Rápido

Recursos Principais

Configuração

A partir de Variáveis de Ambiente

Configuração Manual

Modo de Teste

Timeouts e Retentativas

Operações Comuns

Criar uma Sessão de Checkout

Criar um Produto

Ativar Chave de Licença

Cobrança Baseada em Uso

Registrar Eventos de Uso

Operações Assíncronas

Cliente Assíncrono

Tratamento de Erros

Tratamento Funcional de Erros

Integração com Android

Validação de Resposta

Recursos Avançados

Configuração de Proxy

Configuração Temporária

Integração com Ktor

Recursos

Suporte

Contribuindo