Kotlin - Dodo Payments Documentation

Kotlin SDKは、Kotlinで書かれたアプリケーションからDodo Payments REST APIへの便利なアクセスを提供します。ヌル可能な値、Sequence、suspend関数、その他のKotlin特有の機能を備えており、使いやすさを考慮しています。

インストール

Gradle (Kotlin DSL)

依存関係をbuild.gradle.ktsに追加してください:

build.gradle.kts

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

Maven

依存関係をpom.xmlに追加してください:

pom.xml

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

最新の Dodo Payments 機能にアクセスするには常に最新の SDK バージョンを使用してください。最新バージョンはMaven Centralで確認してください。

この SDK は Java 8 以降が必要で、JVM と Android プラットフォームの両方と互換性があります。

クイックスタート

クライアントを初期化し、チェックアウトセッションを作成します:

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

API キーは環境変数や暗号化された設定を使用して安全に保管してください。決してバージョン管理にコミットしないでください。

コア機能

Coroutines

非同期処理のための Kotlin コルーチンを完全サポート

Null Safety

Kotlin のヌルセーフ機能を活用して堅牢なエラーハンドリングを実現

Extension Functions

機能拡張のための慣用的な Kotlin 拡張

Data Classes

コピーおよび分解構文をサポートする型安全なデータクラス

設定

環境変数から

環境変数またはシステムプロパティから初期化します:

val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv()

手動設定

すべてのオプションで手動で設定します:

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環境用に設定します：

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

タイムアウトとリトライ

グローバルまたはリクエストごとに設定します:

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

一般的な操作

チェックアウトセッションの作成

チェックアウトセッションを生成します:

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

商品の作成

詳細な設定で商品を作成します:

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

ライセンスキーの有効化

顧客のためにライセンスキーを有効化します:

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

サブスクリプションの処理

定期サブスクリプションを作成し管理します：

POST /subscriptions（SDKのsubscriptions.createメソッド）は非推奨です。既存の統合では引き続き動作しますが、新しい統合では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には、最低でも2文字のISO countryコードが必要です。既存の顧客を関連付けるにはAttachExistingCustomerを使用し、新しい顧客を作成するにはNewCustomerを使用します。productPriceは、通貨の最小単位で表されます。

使用量ベースの請求

使用量イベントの記録

メーターの使用量を追跡します：

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

非同期操作

非同期クライアント

コルーチンベースの操作には非同期クライアントを使用します：

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

エラー処理

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

関数型エラー処理

関数型のエラー処理にはResultを使用します：

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

Result型を使用した、より関数型のエラー処理にはKotlinのrunCatchingを使用します。

Android統合

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

レスポンスの検証

レスポンスの検証を有効にします：

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

高度な機能

プロキシ設定

プロキシ設定を構成します：

import java.net.InetSocketAddress
import java.net.Proxy

val client = DodoPaymentsOkHttpClient.builder()
    .fromEnv()
    .proxy(
        Proxy(
            Proxy.Type.HTTP,
            InetSocketAddress("proxy.example.com", 8080)
        )
    )
    .build()

一時的な設定

クライアント設定を一時的に変更します：

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

Ktor統合

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

リソース

GitHub Repository

ソースコードを表示して貢献する

API Reference

APIドキュメント一式

Discord Community

ヘルプを受け、開発者とつながる

Report Issues

バグを報告、または機能をリクエストする

サポート

Kotlin SDKについてサポートが必要ですか？

Discord：コミュニティサーバーに参加して、リアルタイムのサポートを受けられます
メール：support@dodopayments.comまでお問い合わせください
GitHub：リポジトリでissueを作成してください

コントリビューション

コントリビューションを歓迎します！開始するには、コントリビューションガイドラインを確認してください。

​インストール

​Gradle (Kotlin DSL)

​Maven

​クイックスタート

​コア機能

Coroutines

Null Safety

Extension Functions

Data Classes

​設定

​環境変数から

​手動設定

​テストモード

​タイムアウトとリトライ

​一般的な操作

​チェックアウトセッションの作成

​商品の作成

​ライセンスキーの有効化

​サブスクリプションの処理

​使用量ベースの請求

​使用量イベントの記録

​非同期操作

​非同期クライアント

​エラー処理

​関数型エラー処理

​Android統合

​レスポンスの検証

​高度な機能

​プロキシ設定

​一時的な設定

​Ktor統合

​リソース

GitHub Repository

API Reference

Discord Community

Report Issues

​サポート

​コントリビューション

インストール

Gradle (Kotlin DSL)

Maven

クイックスタート

コア機能

設定

環境変数から

手動設定

テストモード

タイムアウトとリトライ

一般的な操作

チェックアウトセッションの作成

商品の作成

ライセンスキーの有効化

サブスクリプションの処理

使用量ベースの請求

使用量イベントの記録

非同期操作

非同期クライアント

エラー処理

関数型エラー処理

Android統合

レスポンスの検証

高度な機能

プロキシ設定

一時的な設定

Ktor統合

リソース

サポート

コントリビューション