Android

このページでは、Android checkout SDK（com.dodopayments.api:checkout-android）について説明します。この SDK はアプリ内で Dodo Payments hosted checkout を開きます。サーバーから Dodo Payments API を呼び出すには、代わりに backend Kotlin SDK を使用してください。

Checkout Sessions API

この SDK が開く checkout_url を作成します。

Mobile Integration Guide

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

Android SDK は Dodo Payments hosted checkout を Custom Tab（androidx.browser.customtabs）で開き、顧客が checkout を完了または離脱したときに型付きの CheckoutResult を返します。バックエンドは checkout session を作成し、その checkout_url をアプリに送信します。SDK にはネットワークコードが含まれず、API key も保持しないため、Dodo Payments API を呼び出すことはありません。 要件: minSdk 23、Kotlin、および Java 17。SDK は androidx.activity、androidx.browser、kotlinx-coroutines-android のみに依存します。

インストール

Add the Dependency

Maven Central から SDK をアプリモジュールの build.gradle.kts に追加します。

build.gradle.kts

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

Appearance customization にはバージョン 1.1.0 以降が必要です。

コールバック scheme を Gradle manifest placeholder として設定します。SDK 自体の manifest はリダイレクト activity の intent filter を ${dodoCallbackScheme} placeholder とともに宣言するため、このプロパティの設定だけで完了します。manifest XML を追加する必要はありません。

build.gradle.kts

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

CheckoutParams.returnUrl では同じ scheme を使用します。たとえば myapp://checkout/return のように指定し、バックエンドで session を作成するときに checkout session の return_url に同じ URL を設定します。SDK は scheme、host、path に基づいて return URL を照合し、query string は無視します。この URL で実際のページを読み込む必要はありません。

placeholder を省略すると、未解決の placeholder エラーでビルドが失敗します。placeholder が returnUrl の scheme と一致しない場合、SDK は checkout を開く前に PLATFORM_ERROR をスローします。

使用方法

SDK には checkout を開始する方法が 2 つあります。activity result launcher と suspend function です。どちらも同じ CheckoutResult を返します。

Launcher (Recommended)
Suspend Function

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

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

// showSuccess(), showFailure(), showExpired(), and reconcileAbandonedSession()
// are your own functions. See Abandoned Sessions for what to reconcile.
private val checkoutLauncher =
    registerForActivityResult(DodoCheckout.contract()) { result ->
        when (result.status) {
            CheckoutStatus.SUCCEEDED -> showSuccess(result.paymentId)
            CheckoutStatus.FAILED -> showFailure()
            CheckoutStatus.CANCELLED -> reconcileAbandonedSession() // outcome unknown, not a failure
            CheckoutStatus.PENDING -> reconcileAbandonedSession()
            CheckoutStatus.EXPIRED -> showExpired()
        }
    }

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

可能な場合はこの方法を使用してください。Android は ActivityResultRegistry を通じて結果を配信するため、プロセスが終了しても結果が保持されます。

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

import androidx.lifecycle.lifecycleScope
import com.dodopayments.checkout.CheckoutParams
import com.dodopayments.checkout.CheckoutStatus
import com.dodopayments.checkout.DodoCheckout
import kotlinx.coroutines.launch

// showSuccess(), showFailure(), showExpired(), and reconcileAbandonedSession()
// are your own functions. See Abandoned Sessions for what to reconcile.
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 -> reconcileAbandonedSession() // outcome unknown, not a failure
        CheckoutStatus.PENDING -> reconcileAbandonedSession()
        CheckoutStatus.EXPIRED -> showExpired()
    }
}

onEvent は checkout.opened、checkout.return_received、checkout.closed のイベントを受け取ります。これらはロギングのみに使用し、結果の判定には決して使用しないでください。

この方法はメモリ内の CompletableDeferred を待機するため、結果はプロセス終了後も保持されません。onEvent はこの方法でのみ使用でき、launcher では使用できません。

結果の意味

SDK は return URL の query parameters から CheckoutResult を構築します。

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

CheckoutStatus

必須

次の 5 つの値のいずれかです。

SUCCEEDED: return URL に status=succeeded（one-time payment）または status=active（subscription）が含まれています。
FAILED: 支払いが拒否されました（status=failed）。
CANCELLED: return URL が届く前に顧客が Custom Tab を閉じました。SDK は結果を把握できず、支払いが成功している可能性もあるため、失敗画面を表示しないでください。代わりに abandoned session を照合してください。
PENDING: 支払いが後で確定します（status=processing または任意の requires_* 値）。または status parameter が欠落しているか認識されませんでした。CANCELLED と同様に照合してください。
EXPIRED: checkout session の有効期限が切れました（status=expired）。

String?

return URL に含まれる場合の payment_id query parameter です。UI に表示しますが、アクセス許可の判断には使用しないでください。支払いを検証するを参照してください。

String?

subscription_id query parameter です。subscription checkout に設定されます。

List<String>?

license_key query parameter です。checkout に license key products が含まれる場合に設定されます。

String?

email query parameter です。checkout でメールアドレスを取得すると設定されます。

Map<String, String>

return URL のすべての query parameter をそのまま返します。

支払いを検証する

Webhooks

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

Get Payment Detail

必要に応じて支払いステータスを照会します。

これらのいずれかによって支払いが確認された後にのみアクセスを許可してください。たとえば payment.succeeded または subscription.active webhook を使用します。CheckoutResult.status だけに依存しないでください。

外観のカスタマイズ

Custom Tab の toolbar、buttons、color scheme を変更するには、CheckoutParams の customization として BrowserCustomization を渡します。すべての field は省略可能で、デフォルトは null です。null field の場合、SDK はその option を設定しないため、Custom Tab をホストする browser 独自のデフォルトが適用されます。

toolbar の背景色を ARGB Color int として指定します。

navigation bar の色を ARGB Color int として指定します。

navigation bar 上部の divider の色を ARGB Color int として指定します。

CloseButtonStyle?

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

CloseButtonPosition?

close button が表示される toolbar の側を指定します。START または END です。

toolbar の share icon を表示します。false はこれを非表示にします。

Boolean?

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

Boolean?

ページのスクロール時に toolbar を自動的に非表示にします。

Boolean?

overflow menu に「このページをブックマーク」を表示します。

Boolean?

overflow menu に「ページをダウンロード」を表示します。

ColorScheme?

LIGHT または DARK は、デバイスのシステム設定に関係なく、その外観を強制します。SYSTEM はシステム設定に従います。

この例では、Usage の checkoutLauncher を再利用します。

import android.graphics.Color
import com.dodopayments.checkout.BrowserCustomization
import com.dodopayments.checkout.CheckoutParams

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: checkoutUrl は、checkout.dodopayments.com または test.checkout.dodopayments.com 上の、/session/ で始まる path を持つ https checkout session URL ではありません。
INVALID_RETURN_URL: returnUrl は scheme と host を持つ absolute URL ではありません。
ALREADY_IN_PROGRESS: 別の checkout が実行中です。一度に実行できる checkout は 1 つだけです。
PLATFORM_ERROR: returnUrl scheme が dodoCallbackScheme placeholder と一致しない場合を含む、予期しないプラットフォーム障害です。

顧客によるキャンセルや支払いの拒否は、常に結果（CANCELLED または FAILED）として返され、スローされるエラーではありません。launcher では、検証エラーは launcher.launch(...) からスローされます。起動後のプラットフォーム障害は activity result callback を通じてスローできないため、launcher は raw["error"] にエラーコードを含む CANCELLED を返します。

放棄されたセッション

SDK は checkout の開始時に checkout session を記録し、checkout が SUCCEEDED、FAILED、または EXPIRED で終了した場合にのみ記録を消去します。checkout 中にアプリが終了した場合、または CANCELLED や PENDING の結果が返された場合は、記録が残ります。これは、SDK が結果を把握できないためです。次回のアプリ起動時、および CANCELLED または PENDING の結果が返るたびに確認してください。

// context is any Context, such as your Activity.
DodoCheckout.getAbandonedSession(context)?.let { abandoned ->
    // Ask your backend for the outcome of abandoned.sessionId, and show it.
    // Clear the record only after the outcome is final:
    DodoCheckout.clearAbandonedSession(context)
}

abandoned.sessionId は checkout session ID で、cks_ で始まります。abandoned.createdAt は checkout の開始時刻で、ミリ秒単位の epoch timestamp です。バックエンドでは Get Checkout Session を使用して session を検索できます。この API は payment_id と payment_status を返します。支払いが final status に達するまでは、失敗ではなく pending として扱ってください。

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

インストール

使用方法

結果の意味

支払いを検証する

外観のカスタマイズ

エラー

放棄されたセッション

関連情報