Kotlin - Dodo Payments Documentation

Kotlin SDK를 사용하면 Kotlin 애플리케이션에서 Dodo Payments REST API에 타입이 지정된 방식으로 액세스할 수 있습니다. 전체적으로 Kotlin types를 사용합니다. 누락될 수 있는 필드에는 nullable values를 사용하고, 결과를 반복할 때는 Sequence를 사용하며, 비동기 호출에는 suspend 함수를 사용합니다.

설치

Gradle (Kotlin DSL)

종속성을 build.gradle.kts에 추가하세요:

build.gradle.kts

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

Maven

종속성을 pom.xml에 추가하세요:

pom.xml

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

SDK 릴리스에는 API 변경 사항에 대한 지원이 추가됩니다. 최신 버전을 확인하려면 Maven Central을 확인하세요.

SDK에는 Java 8 이상이 필요합니다. JVM과 Android에서 실행되며 ProGuard 및 R8 keep rules가 포함되어 있습니다.

빠른 시작

클라이언트를 생성한 다음 checkout session을 생성합니다:

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
import com.dodopayments.api.models.checkoutsessions.ProductItemReq

// Configure using environment variables (DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_WEBHOOK_KEY, DODO_PAYMENTS_BASE_URL)
// Or system properties (dodopayments.apiKey, dodopayments.webhookKey, dodopayments.baseUrl)
val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv()

val params: CheckoutSessionRequest = CheckoutSessionRequest.builder()
    .addProductCart(ProductItemReq.builder()
        .productId("pdt_123")
        .quantity(1)
        .build())
    .build()
    
val checkoutSessionResponse: CheckoutSessionResponse = client.checkoutSessions().create(params)
println(checkoutSessionResponse.sessionId())

fromEnv()는 DODO_PAYMENTS_BASE_URL 또는 dodopayments.baseUrl에서 별도로 지정하지 않는 한 live mode에 연결합니다. test mode를 사용하려면 Test Mode를 참조하세요. test mode API key는 test mode에서만 작동합니다.

API keys는 environment variables 또는 secrets manager에 보관하세요. 절대로 version control에 커밋하지 마세요.

핵심 기능

Coroutines

async client의 메서드는 suspend 함수이며 coroutine에서 호출합니다.

Null Safety

누락될 수 있는 필드는 Optional가 아닌 nullable types입니다.

Sequences

synchronous client에서 autoPager()는 반복할 때 더 많은 페이지를 가져오는 Sequence를 반환합니다. async client에서는 Flow를 반환합니다.

Immutable Models

Model classes는 immutable이며, toBuilder()는 수정된 복사본을 위한 builder를 반환합니다.

Configuration

Environment Variables에서 가져오기

fromEnv()는 environment variables 또는 system properties에서 설정을 읽습니다. system properties가 우선합니다:

val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv()

API key는 DODO_PAYMENTS_API_KEY 또는 dodopayments.apiKey에서 가져옵니다. webhook signing secret은 DODO_PAYMENTS_WEBHOOK_KEY 또는 dodopayments.webhookKey에서, base URL은 DODO_PAYMENTS_BASE_URL 또는 dodopayments.baseUrl에서 가져옵니다. 각 client에는 자체 connection pool과 thread pools가 있으므로 client 하나를 생성하고 재사용하세요. webhook을 검증하려면 raw request body와 headers를 client.webhooks().unwrap(UnwrapWebhookParams.builder().body(rawBody).headers(headers).build())에 전달하세요. 이때 headers는 com.dodopayments.api.core.http.Headers입니다. 이 함수는 webhook key로 signature를 확인하고 파싱된 event를 반환하거나 DodoPaymentsWebhookException를 throw합니다. headers가 없으면 unwrap는 signature를 검증하지 않습니다. client.webhooks().unsafeUnwrap(rawBody)는 검증 없이 body를 파싱하므로 testing에만 사용하세요. Webhooks를 참조하세요.

Manual Configuration

builder에서 각 option을 설정합니다:

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

Test Mode

test mode(https://test.dodopayments.com)를 사용하려면 builder에서 testMode()를 호출합니다:

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

Timeouts 및 Retries

기본적으로 client는 두 번 재시도하며 1분 후 timeout됩니다. connection errors와 status가 408, 409, 429 또는 500 이상인 responses를 exponential backoff 방식으로 재시도합니다. client에서 defaults를 설정하거나 단일 call에 RequestOptions를 전달할 수 있습니다:

import com.dodopayments.api.core.RequestOptions
import java.time.Duration

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

일반 작업

이 섹션의 예제에서는 Quick Start의 client를 사용합니다.

Checkout Session 생성

checkout session을 생성한 다음 반환된 checkout URL로 customer를 redirect합니다:

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

checkoutUrl()는 nullable String?를 반환합니다. 각 checkout URL은 한 번만 사용할 수 있으며 24시간 후 만료됩니다. 모든 session option은 Checkout Sessions를 참조하세요.

Product 생성

가격이 $29.99인 monthly subscription product를 생성합니다:

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.subscriptions.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
            .discountBps(0)
            .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()}")

price는 가장 작은 currency unit으로 표시됩니다. discountBps는 discount를 basis points로 설정하며 deprecated된 discount field를 대체합니다.

License Key 활성화

device 또는 installation에 대한 license key를 활성화합니다. key가 activation limit에 도달하면 API는 422를 반환하고 SDK는 UnprocessableEntityException를 throw합니다. 비활성 key는 403(PermissionDeniedException)를 반환하고, 알 수 없는 key는 404(NotFoundException)를 반환합니다:

import com.dodopayments.api.errors.UnprocessableEntityException
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}")
}

Subscriptions 처리

subscription을 생성한 다음 on-demand subscription인 경우 charge합니다.

POST /subscriptions(SDK의 subscriptions().create() method)은 deprecated되었습니다. 기존 integration에서는 계속 작동하지만, 새로운 integration에서는 Checkout Session을 통해 subscription을 생성해야 합니다.

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에는 두 글자로 된 ISO country code인 country만 필요합니다. 기존 customer를 연결하려면 AttachExistingCustomer를 사용하고, customer를 생성하려면 NewCustomer를 사용하세요. charge는 on-demand subscriptions에 사용하며, productPrice는 가장 작은 currency unit으로 표시됩니다.

Usage-Based Billing

Usage Events 기록

customer에 usage event를 전송합니다. event의 eventName를 추적하는 meters가 해당 event를 집계합니다:

import com.dodopayments.api.models.usageevents.EventInput
import com.dodopayments.api.models.usageevents.UsageEventIngestParams

val usageParams = UsageEventIngestParams.builder()
    .addEvent(EventInput.builder()
        .customerId("cus_456")
        .eventId("event_123")
        .eventName("api_call")
        .build())
    .build()

client.usageEvents().ingest(usageParams)
println("Usage event recorded")

eventId는 idempotency key이므로 각 event에 고유한 값을 지정하세요. 하나의 request에는 최대 1,000개의 event를 포함할 수 있습니다.

비동기 작업

Async Client

async client에는 synchronous client와 동일한 메서드가 있지만, 대부분 suspend 함수입니다. coroutine에서 호출하세요:

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("cus_123")
    println("Customer email: ${customer.email()}")
}

synchronous client에서 client.async()를 호출하여 async version을 가져올 수도 있습니다.

Error Handling

error status가 발생하면 SDK는 DodoPaymentsServiceException의 subclass를 throw합니다. 이 subclass에는 statusCode(), headers() 및 body()가 있습니다. Subclass는 BadRequestException(400), UnauthorizedException(401), PermissionDeniedException(403), NotFoundException(404), UnprocessableEntityException(422), RateLimitException(429), InternalServerException(5xx), 그리고 409와 같은 기타 status를 위한 UnexpectedStatusCodeException입니다:

import com.dodopayments.api.errors.*

try {
    // Note: POST /payments is deprecated — prefer checkout sessions for new
    // integrations. Shown here only to illustrate error handling.
    // paymentParams is a PaymentCreateParams with billing, customer, and productCart.
    val payment = client.payments().create(paymentParams)
    println("Success: ${payment.paymentId()}")
} catch (e: UnauthorizedException) {
    println("Authentication failed: ${e.message}")
} catch (e: BadRequestException) {
    println("Invalid request: ${e.message}")
    println("Response body: ${e.body()}")
} catch (e: RateLimitException) {
    println("Rate limit exceeded, retry after: ${e.headers().values("retry-after")}")
} catch (e: DodoPaymentsServiceException) {
    println("API error: ${e.statusCode()} - ${e.message}")
}

Network failures는 DodoPaymentsIoException를 throw하고, SDK가 해석할 수 없는 responses는 DodoPaymentsInvalidDataException를 throw합니다. 모든 SDK exceptions는 DodoPaymentsException를 extend합니다.

Functional Error Handling

functional error handling에는 Result를 사용합니다:

import com.dodopayments.api.client.DodoPaymentsClient
import com.dodopayments.api.models.payments.PaymentCreateResponse

fun safeCreatePayment(client: DodoPaymentsClient): Result<PaymentCreateResponse> = runCatching {
    // Note: POST /payments is deprecated — prefer checkout sessions for new integrations
    // paymentParams is a PaymentCreateParams with billing, customer, and productCart.
    client.payments().create(paymentParams)
}

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

runCatching는 SDK exceptions를 포함한 모든 exception을 catch하고, 이를 실패한 Result로 반환합니다.

Android Integration

Kotlin SDK는 서버 SDK입니다. secret API key로 인증하며, APK를 가진 누구나 APK에 컴파일된 키를 추출할 수 있으므로 Android 앱 내부에서 절대 사용하지 마세요. Android 앱에서 결제를 처리하려면:

서버에서 이 SDK로 checkout session을 생성하고(Ktor Integration 참조) checkout_url을 반환합니다.
앱에서 서버로부터 해당 checkout_url을 가져온 다음, API key가 포함되지 않은 Android SDK를 사용해 엽니다.

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.launch

class PaymentViewModel(private val api: YourBackendApi) : ViewModel() {
    fun createCheckout(productId: String) {
        viewModelScope.launch {
            // Your backend creates the session with the Kotlin SDK and returns checkout_url.
            // YourBackendApi and openCheckout are your app's own code; openCheckout
            // passes the URL to DodoCheckout from the Android SDK.
            val checkoutUrl = api.createCheckoutSession(productId).checkoutUrl
            openCheckout(checkoutUrl)
        }
    }
}

응답 검증

기본적으로 SDK는 예상하지 못한 타입의 속성을 읽을 때만 DodoPaymentsInvalidDataException을 발생시킵니다. 전체 응답을 미리 확인하려면 요청에 validation을 활성화하거나, 응답에서 validate()을 호출하세요:

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

고급 기능

Proxy 구성

Proxy를 통해 요청을 전송하려면 builder에 java.net.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()

임시 구성

withOptions은 원래 client의 connection 및 thread pool을 공유하면서 설정이 변경된 client를 반환합니다. 원래 client는 변경되지 않습니다:

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

Ktor Integration

client를 한 번 생성하고 route에서 호출하세요:

import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient
import com.dodopayments.api.errors.DodoPaymentsServiceException
import com.dodopayments.api.models.checkoutsessions.CheckoutSessionRequest
import com.dodopayments.api.models.checkoutsessions.ProductItemReq
import io.ktor.http.HttpStatusCode
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 {
                // CheckoutRequest is your own @Serializable request class with a productId field
                val request = call.receive<CheckoutRequest>()
                val params = CheckoutSessionRequest.builder()
                    .addProductCart(ProductItemReq.builder().productId(request.productId).quantity(1).build())
                    .build()
                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))
            }
        }
    }
}

리소스

GitHub Repository

소스 코드, 릴리스 및 전체 메서드 목록입니다.

API Reference

모든 endpoint, parameter 및 response입니다.

Discord Community

질문하고 다른 개발자들과 소통하세요.

Report Issues

버그를 신고하거나 기능을 요청하세요.

지원

Kotlin SDK에 대한 도움이 필요하다면 다음을 이용하세요:

Discord: 실시간 지원을 받으려면 커뮤니티 서버에 참여하세요.
Email: support@dodopayments.com으로 문의하세요.
GitHub: repository에 issue를 등록하세요.

기여

기여하려면 기여 가이드라인을 읽어보세요.

​설치

​Gradle (Kotlin DSL)

​Maven

​빠른 시작

​핵심 기능

Coroutines

Null Safety

Sequences

Immutable Models

​Configuration

​Environment Variables에서 가져오기

​Manual Configuration

​Test Mode

​Timeouts 및 Retries

​일반 작업

​Checkout Session 생성

​Product 생성

​License Key 활성화

​Subscriptions 처리

​Usage-Based Billing

​Usage Events 기록

​비동기 작업

​Async Client

​Error Handling

​Functional Error Handling

​Android Integration

​응답 검증

​고급 기능

​Proxy 구성

​임시 구성

​Ktor Integration

​리소스

GitHub Repository

API Reference

Discord Community

Report Issues

​지원

​기여

설치

Gradle (Kotlin DSL)

Maven

빠른 시작

핵심 기능

Configuration

Environment Variables에서 가져오기

Manual Configuration

Test Mode

Timeouts 및 Retries

일반 작업

Checkout Session 생성

Product 생성

License Key 활성화

Subscriptions 처리

Usage-Based Billing

Usage Events 기록

비동기 작업

Async Client

Error Handling

Functional Error Handling

Android Integration

응답 검증

고급 기능

Proxy 구성

임시 구성

Ktor Integration

리소스

지원

기여