Android

これは、Dodoのホスト型チェックアウトを開くための公式AndroidチェックアウトSDK（com.dodopayments.api:checkout-android）です。サーバーからDodo Payments APIを呼び出すbackend Kotlin SDKとは異なります。

Checkout Sessions API

このSDKが開くcheckout_urlを作成する

Mobile Integration Guide

モバイルチェックアウトフローのベストプラクティス

Android SDKは、androidx.browser.customtabsを使用して、Dodoのホスト型チェックアウトをChrome Custom Tabで開きます。ネットワークコードは一切含まず、API keyも保持しません。バックエンドのcheckout sessionからcheckoutUrlを渡すと、ユーザーがフローを完了または中止したときに、SDKは型付きのCheckoutResultを返します。 要件: minSdk 23、Kotlin、Java 17。

インストール

Add the Dependency

build.gradle.kts

dependencies {
    implementation("com.dodopayments.api:checkout-android:1.0.0")
}

コールバックスキームをGradle manifest placeholderとして設定します。ライブラリ独自の manifestでは、すでにリダイレクトアクティビティのintent filterが ${dodoCallbackScheme}トークンを使って宣言されています。そのため、この1つのプロパティだけで設定は完了します。 manifest XMLを追加する必要はありません。

build.gradle.kts

android {
    defaultConfig {
        manifestPlaceholders["dodoCallbackScheme"] = "myapp"
    }
}

値はCheckoutParams.returnUrl内のスキーム（例: myapp://checkout/return）と一致する必要があります。

placeholderを完全に省略すると、チェックアウト時に何も起こらず失敗するのではなく、 unresolved-placeholderエラーですぐにビルドが失敗します。設定した値がreturnUrlのスキームと一致しない場合、DodoCheckout.startは何も表示する前にPLATFORM_ERRORをスローします。

使用方法

SDKは2種類の呼び出し方法に対応しています。

Launcher (Recommended)
Suspend Function

registerForActivityResultにコントラクトを登録してから、起動します。

import com.dodopayments.checkout.CheckoutParams
import com.dodopayments.checkout.CheckoutStatus
import com.dodopayments.checkout.DodoCheckout

private val checkoutLauncher =
    registerForActivityResult(DodoCheckout.contract()) { result ->
        when (result.status) {
            CheckoutStatus.SUCCEEDED -> showSuccess(result.paymentId)
            CheckoutStatus.FAILED -> showFailure()
            CheckoutStatus.CANCELLED -> dismiss()
            CheckoutStatus.PENDING -> showPending()
            CheckoutStatus.EXPIRED -> showExpired()
        }
    }

checkoutLauncher.launch(
    CheckoutParams(
        checkoutUrl = checkoutUrl, // from your backend's checkout session
        returnUrl = "myapp://checkout/return"
    )
)

この方法を推奨します。結果はAndroidのOSが管理するActivityResultRegistryを通じて渡されるため、プロセスが終了しても保持されます。

コルーチンスコープからDodoCheckout.startを呼び出します。

import com.dodopayments.checkout.CheckoutParams
import com.dodopayments.checkout.CheckoutStatus
import com.dodopayments.checkout.DodoCheckout

lifecycleScope.launch {
    val result = DodoCheckout.start(
        activity = this@MyActivity,
        params = CheckoutParams(
            checkoutUrl = checkoutUrl, // from your backend's checkout session
            returnUrl = "myapp://checkout/return"
        ),
        onEvent = { event -> println(event.name) } // logging only
    )

    when (result.status) {
        CheckoutStatus.SUCCEEDED -> showSuccess(result.paymentId)
        CheckoutStatus.FAILED -> showFailure()
        CheckoutStatus.CANCELLED -> dismiss()
        CheckoutStatus.PENDING -> showPending()
        CheckoutStatus.EXPIRED -> showExpired()
    }
}

この方法ではメモリ上のCompletableDeferredを解決するため、プロセスが終了しても保持されません。onEventはこの方法でのみ利用でき、コントラクトでは利用できません。

結果の意味

statusフィールドはUI上のヒントであり、支払いの証明ではありません。アクセスを許可する前に、必ずwebhooksまたはGet Payment Detail endpointを使用してバックエンドで支払いを検証してください。

CheckoutStatus

必須

SUCCEEDED、FAILED、CANCELLED、PENDING、EXPIREDのいずれか1つ。

String?

return URLに含まれている場合に設定されます。UIに表示しますが、アクセスの許可には使用しないでください。下記の「支払いの検証」を参照してください。

String?

subscription checkoutの場合に設定されます。

List<String>?

チェックアウトにlicense key productsが含まれている場合に設定されます。

String?

チェックアウトでemailを取得した場合に設定されます。

Map<String, String>

return URLのすべてのquery parameterを、そのまま保持します。

支払いの検証

Webhooks

支払いイベントをリアルタイムでリッスンする

Get Payment Detail

必要に応じて支払いステータスをクエリする

これらのいずれかによって支払いが確認された後にのみ、ユーザーにアクセスを許可してください。CheckoutResult.statusだけに依存しないでください。

エラー

DodoCheckout.startがCheckoutErrorをスローするのは、誤った使用またはプラットフォーム障害の場合のみです。コードはCheckoutError.codeから読み取ります。

INVALID_CHECKOUT_URL: checkout.dodopayments.com session URLではありません。
INVALID_RETURN_URL: 有効なabsolute URLではありません。
ALREADY_IN_PROGRESS: checkoutがすでに実行中です。
PLATFORM_ERROR: dodoCallbackScheme placeholderとスキームが一致しないreturnUrlを含む、予期しないプラットフォーム障害。

ユーザーによるキャンセルや支払いの拒否は、常に結果（CANCELLEDまたはFAILED）として返され、スローされるエラーにはなりません。launcher styleでは、検証エラーはlauncher.launch(...)の外部にスローされます。

放棄されたセッション

チェックアウト中にアプリが終了したり、ユーザーがアプリを強制停止したりすると、SDKはセッションをローカルに保存します。次回アプリを起動したときに、放棄されたセッションがないか確認し、バックエンドと照合してください。

DodoCheckout.getAbandonedSession(context)?.let { abandoned ->
    // reconcile abandoned.sessionId with your backend, then:
    DodoCheckout.clearAbandonedSession(context)
}

abandoned.createdAtは、ミリ秒単位のepoch timestampです。

Mobile Integration Guide

モバイルチェックアウトフローのベストプラクティス

Kotlin SDK

サーバーサイド操作用のBackend SDK

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

インストール

使用方法

結果の意味

支払いの検証

Webhooks

Get Payment Detail

エラー

放棄されたセッション

関連情報

Mobile Integration Guide

Kotlin SDK

Checkout Sessions API

Mobile Integration Guide

​インストール

​使用方法

​結果の意味

​支払いの検証

Webhooks

Get Payment Detail

​エラー

​放棄されたセッション

​関連情報

Mobile Integration Guide

Kotlin SDK

インストール

使用方法

結果の意味

支払いの検証

エラー

放棄されたセッション

関連情報