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 o ambiente Test Mode:

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

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

Criar um Produto

Crie produtos com configuração detalhada:

import com.dodopayments.api.models.products.Price
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
import com.dodopayments.api.models.misc.TimeInterval

val createParams = ProductCreateParams.builder()
    .name("Premium Subscription")
    .description("Monthly subscription with all features")
    .price(
        Price.RecurringPrice.builder()
            .currency(Currency.USD)
            .price(2999) // $29.99 in cents
            .discount(0L)
            .purchasingPowerParity(false)
            .paymentFrequencyCount(1)
            .paymentFrequencyInterval(TimeInterval.MONTH)
            .subscriptionPeriodCount(1)
            .subscriptionPeriodInterval(TimeInterval.MONTH)
            .build()
    )
    .taxCategory(TaxCategory.DIGITAL_PRODUCTS)
    .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")
    .name("user-laptop-01")
    .build()

try {
    val activationResult: LicenseActivateResponse = client.licenses()
        .activate(activateParams)

    println("License activated successfully")
    println("Instance ID: ${activationResult.id()}")
    println("License key ID: ${activationResult.licenseKeyId()}")
} catch (e: UnprocessableEntityException) {
    println("License activation failed: ${e.message}")
}

Cobrança Baseada em Uso

Registrar Eventos de Uso

POST /subscriptions (o método subscriptions.create do SDK) está deprecated. Ele ainda funciona para integrações existentes, mas novas integrações devem criar assinaturas por meio de uma Checkout Session.

import com.dodopayments.api.models.payments.AttachExistingCustomer
import com.dodopayments.api.models.payments.BillingAddress
import com.dodopayments.api.models.misc.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 requer, no mínimo, um código ISO country de duas letras. Use AttachExistingCustomer para associar um customer existente ou NewCustomer para criar um. productPrice é expresso na menor denominação da moeda.

Faturamento baseado em uso

Registrar eventos de uso

Acompanhe o uso dos 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")

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 usando o tratamento de exceções do Kotlin:

import com.dodopayments.api.errors.*

try {
    val payment = client.payments().create(params)
    println("Success: ${payment.paymentId()}")
} 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 o tratamento funcional de erros:

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

// Usage
safeCreatePayment(client)
    .onSuccess { payment -> println("Created: ${payment.paymentId()}") }
    .onFailure { error -> println("Error: ${error.message}") }

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

Integração com Android

Use com aplicativos 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)
            }
        }
    }
}

Validação de respostas

Ative a validação de respostas:

import com.dodopayments.api.core.RequestOptions

// Per-request validation
val product = client.products().retrieve(
    "pdt_123",
    RequestOptions.builder()
        .responseValidation(true)
        .build()
)

// Or validate explicitly
val validatedProduct = product.validate()

Recursos avançados

Configuração de proxy

Configure as definiçõ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 temporariamente a configuração do cliente:

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

Integração com Ktor

Integre com aplicativos 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

Visualize o código-fonte e contribua

API Reference

Documentação completa da API

Discord Community

Obtenha ajuda e conecte-se com desenvolvedores

Report Issues

Relate bugs ou solicite recursos

Suporte

Precisa de ajuda com o Kotlin SDK?

Discord: participe do nosso servidor da comunidade para receber suporte em tempo real
E-mail: entre em contato conosco pelo endereço support@dodopayments.com
GitHub: abra uma issue no repositório

Como contribuir

Aceitamos contribuições! Consulte as diretrizes de contribuição para começar.

​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

​Faturamento baseado 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 respostas

​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

​Como contribuir

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

Faturamento baseado 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 respostas

Recursos avançados

Configuração de proxy

Configuração temporária

Integração com Ktor

Recursos

Suporte

Como contribuir