Kotlin - Dodo Payments Documentation

Kotlin SDK を使用すると、Kotlin アプリケーションから Dodo Payments REST API に typed access できます。全体を通して Kotlin types を使用しており、存在しない可能性があるフィールドには nullable values、結果の反復処理には Sequence、非同期呼び出しには suspend functions を使用します。

インストール

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 releases では API changes への対応が追加されます。最新バージョンを確認するには、Maven Central を参照してください。

SDK には Java 8 以降が必要です。JVM と Android で動作し、ProGuard および R8 の keep rules が同梱されています。

クイックスタート

client を作成してから、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 に commit しないでください。

Core Features

Coroutines

async client の methods は suspend functions であり、coroutine から呼び出します。

Null Safety

存在しない可能性があるフィールドは、Optional ではなく nullable types です。

Sequences

synchronous client では、autoPager() は Sequence を返します。これは反復処理に応じて追加のページを取得します。async client では、Flow を返します。

Immutable Models

Model classes は immutable であり、toBuilder() は変更された copy 用の builder を返します。

Configuration

From 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 は 1 つ作成して再利用してください。 webhook を verify するには、raw request body と headers を client.webhooks().unwrap(UnwrapWebhookParams.builder().body(rawBody).headers(headers).build()) に渡します。このとき headers は com.dodopayments.api.core.http.Headers です。webhook key を使用して signature を確認し、parsed event を返します。検証に失敗すると DodoPaymentsWebhookException を throw します。headers がない場合、unwrap は signature を verify しません。client.webhooks().unsafeUnwrap(rawBody) は検証せずに body を parse するため、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 and Retries

デフォルトでは、client は 2 回 retry し、1 分後に timeout します。connection errors と、status 408、409、429、または 500 以上の responses に対して、exponential backoff を使用して retry します。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()
)

Common Operations

このセクションの examples では、Quick Start の client を使用します。

Create a 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 は 1 回のみ使用でき、24 時間後に expires します。すべての session options については、Checkout Sessions を参照してください。

Create a 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 は、通貨の最小単位で指定します。discountBps は discount を basis points で設定し、deprecated である discount field を置き換えます。

Activate License Key

device または installation 用の license key を activate します。key が activation limit に達している場合、API は 422 を返し、SDK は UnprocessableEntityException を throw します。inactive key は 403（PermissionDeniedException）を返し、unknown 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}")
}

Handle Subscriptions

subscription を作成し、on-demand subscription の場合は charge します。

POST /subscriptions（SDK の subscriptions().create() method）は deprecated です。既存の integrations では引き続き動作しますが、新しい integrations では Checkout Session を通じて subscriptions を作成してください。

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 に必要なのは、2 文字の ISO country code である country のみです。既存の customer を attach するには AttachExistingCustomer を使用し、customer を作成するには NewCustomer を使用します。charge は on-demand subscriptions 用で、productPrice は通貨の最小単位で指定します。

Usage-Based Billing

Record Usage Events

customer の usage event を送信します。event の eventName を追跡する meters が、その event を aggregate します。

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 に一意の value を指定してください。1 つの request で最大 1,000 件の events を受け付けます。

Async Operations

Async Client

async client には synchronous client と同じ methods がありますが、そのほとんどは suspend functions です。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() があります。subclasses は、BadRequestException（400）、UnauthorizedException（401）、PermissionDeniedException（403）、NotFoundException（404）、UnprocessableEntityException（422）、RateLimitException（429）、InternalServerException（5xx）、および 409 などのその他の statuses 用の 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 を含むすべての exceptions を catch し、failed Result として返します。

Android Integration

Kotlin SDKはserver SDKです。secret API keyで認証を行います。また、APKを持っている人は、そこにコンパイルされたkeyを抽出できるため、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)
        }
    }
}

Response Validation

デフォルトでは、予期しない型のプロパティを読み取った場合にのみ、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()

Advanced Features

Proxy Configuration

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

Temporary Configuration

withOptionsは、変更された設定を持つclientを返します。このclientは、元のclientのconnection poolとthread poolを共有します。元の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))
            }
        }
    }
}

Resources

GitHub Repository

ソースコード、リリース、完全なメソッド一覧。

API Reference

すべてのendpoint、parameter、response。

Discord Community

質問したり、ほかの開発者と交流したりできます。

Report Issues

バグを報告したり、機能をリクエストしたりできます。

Support

Kotlin SDKに関するサポートが必要な場合:

Discord: リアルタイムのサポートを受けるには、community serverに参加してください。
Email: support@dodopayments.comにお問い合わせください。
GitHub: repositoryでissueを作成してください。

Contributing

貢献するには、contributing guidelinesをお読みください。

​インストール

​Gradle (Kotlin DSL)

​Maven

​クイックスタート

​Core Features

Coroutines

Null Safety

Sequences

Immutable Models

​Configuration

​From Environment Variables

​Manual Configuration

​Test Mode

​Timeouts and Retries

​Common Operations

​Create a Checkout Session

​Create a Product

​Activate License Key

​Handle Subscriptions

​Usage-Based Billing

​Record Usage Events

​Async Operations

​Async Client

​Error Handling

​Functional Error Handling

​Android Integration

​Response Validation

​Advanced Features

​Proxy Configuration

​Temporary Configuration

​Ktor Integration

​Resources

GitHub Repository

API Reference

Discord Community

Report Issues

​Support

​Contributing

インストール

Gradle (Kotlin DSL)

Maven

クイックスタート

Core Features

Configuration

From Environment Variables

Manual Configuration

Test Mode

Timeouts and Retries

Common Operations

Create a Checkout Session

Create a Product

Activate License Key

Handle Subscriptions

Usage-Based Billing

Record Usage Events

Async Operations

Async Client

Error Handling

Functional Error Handling

Android Integration

Response Validation

Advanced Features

Proxy Configuration

Temporary Configuration

Ktor Integration

Resources

Support

Contributing