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

Maven

Adicione a dependência ao seu pom.xml:

pom.xml

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

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

O SDK requer Kotlin 1.6 ou superior e é compatível com as plataformas JVM e 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.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())

Sempre armazene suas chaves de API de forma segura usando variáveis de ambiente ou configuração criptografada. Nunca as comite no controle de versão.

Recursos Principais

Corrotinas

Suporte total para corrotinas Kotlin para operações assíncronas

Segurança contra Nulos

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

Funções de Extensão

Extensões idiomáticas do Kotlin para funcionalidade aprimorada

Classes de Dados

Classes de dados seguras em tipo com suporte a cópia e destruição

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

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 tratamento funcional de erros:

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

Use runCatching do Kotlin para uma abordagem mais funcional ao 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

Repositório do GitHub

Veja o código-fonte e contribua

Referência da API

Documentação completa da API

Comunidade Discord

Obtenha ajuda e conecte-se com desenvolvedores

Relatar Problemas

Relate 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 [email protected]
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

Corrotinas

Segurança contra Nulos

Funções de Extensão

Classes de Dados

​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

Repositório do GitHub

Referência da API

Comunidade Discord

Relatar Problemas

​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