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だけに依存しないでください。

外観のカスタマイズ

CheckoutParams 上で customization を使用して、Custom Tab のツールバー、ボタン、配色をカスタマイズできます。すべてのフィールドは任意です。customization を省略すると、Android のデフォルトの Custom Tab 外観が使用されます。

ツールバーの背景色を ARGB Color int として指定します。

ナビゲーションバーの色です。

ナビゲーションバーの上に表示する区切り線の色です。

CloseButtonStyle

DEFAULT はシステムの「X」アイコンを表示し、BACK は代わりに戻る矢印を描画します。

CloseButtonPosition

ツールバーの閉じるボタンを表示する側を指定します。START または END です。

ツールバーの共有アイコンを表示します。

Boolean

ツールバーで URL の下にページタイトルを表示します。

Boolean

ページのスクロールに合わせてツールバーを自動的に非表示にします。

Boolean

オーバーフローメニューに「このページをブックマーク」を表示します。

Boolean

オーバーフローメニューに「ページをダウンロード」を表示します。

ColorScheme

デバイスのシステム設定に関係なく、明るい外観または暗い外観を強制します。指定できる値は SYSTEM、LIGHT、または DARK です。

import com.dodopayments.checkout.BrowserCustomization

checkoutLauncher.launch(
    CheckoutParams(
        checkoutUrl = checkoutUrl,
        returnUrl = "myapp://checkout/return",
        customization = BrowserCustomization(
            toolbarColor = Color.parseColor("#6366F1"),
            closeButtonStyle = BrowserCustomization.CloseButtonStyle.BACK,
            colorScheme = BrowserCustomization.ColorScheme.DARK,
        )
    )
)

エラー

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

INVALID_CHECKOUT_URL: checkout.dodopayments.com セッション URL ではありません。
INVALID_RETURN_URL: 有効な絶対 URL ではありません。
ALREADY_IN_PROGRESS: checkout はすでに実行中です。
PLATFORM_ERROR: dodoCallbackScheme プレースホルダーとスキームが一致しない returnUrl など、予期しないプラットフォーム障害です。

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

放棄されたセッション

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

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

abandoned.createdAt は、ミリ秒単位のエポックタイムスタンプです。

Mobile Integration Guide

モバイル checkout フローのベストプラクティス

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

インストール

使用方法

結果の意味

支払いの検証

外観のカスタマイズ

エラー

放棄されたセッション

関連情報