Android

这是官方的 Android 结账 SDK（com.dodopayments.api:checkout-android），用于打开 Dodo 的托管结账页面。它与 backend Kotlin SDK 不同，后者从你的服务器调用 Dodo Payments API。

Checkout Sessions API

创建此 SDK 打开的 checkout_url

Mobile Integration Guide

移动端结账流程的最佳实践

Android SDK 使用 androidx.browser.customtabs 在 Chrome Custom Tab 中打开 Dodo 的托管结账页面。它不包含任何网络代码，也不持有 API key。你需要传入后端结账会话中的 checkoutUrl，SDK 会在用户完成或放弃流程时返回类型化的 CheckoutResult。 要求： minSdk 23、Kotlin、Java 17。

安装

Add the Dependency

build.gradle.kts

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

将回调 scheme 设置为 Gradle manifest placeholder。该库自己的 manifest 已使用 ${dodoCallbackScheme} token 声明了重定向 activity 的 intent filter，因此这一项属性就是全部配置成本—— 你无需添加 manifest XML：

build.gradle.kts

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

该值必须与 CheckoutParams.returnUrl 中的 scheme 匹配（例如 myapp://checkout/return）。

如果完全省略该 placeholder，构建会立即因 placeholder 未解析而失败，而不是在结账时静默失败。如果设置了该值但它与 returnUrl 的 scheme 不匹配，DodoCheckout.start 会在显示任何内容前抛出 PLATFORM_ERROR。

使用

SDK 支持两种调用方式。

Launcher (Recommended)
Suspend Function

使用 registerForActivityResult 注册 contract，然后启动它：

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 的操作系统管理的 ActivityResultRegistry 传递，因此即使进程终止也能保留。

从 coroutine scope 调用 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 仅在此处可用，在 contract 上不可用。

结果含义

status 字段是 UI 提示，而不是付款成功的证明。在授予访问权限前，始终使用 webhooks 或 Get Payment Detail endpoint 在后端验证付款。

CheckoutStatus

必填

SUCCEEDED、FAILED、CANCELLED、PENDING、EXPIRED 中的一个。

String?

当 return URL 包含该值时设置。将其显示在 UI 中，但不要使用它来授予访问权限。请参阅下方的 Verify the Payment。

String?

用于订阅结账时设置。

List<String>?

当结账包含 license key 产品时设置。

String?

当结账捕获 email 时设置。

Map<String, String>

return URL 中的每个 query parameter，保持原样。

验证付款

Webhooks

实时监听付款事件

Get Payment Detail

按需查询付款状态

只有在其中一种方式确认付款后，才向用户授予访问权限。不要仅依赖 CheckoutResult.status。

外观自定义

通过 customization 在 CheckoutParams 上自定义 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：意外的平台失败，包括 returnUrl 的 scheme 与 dodoCallbackScheme 占位符不匹配的情况。

用户取消操作或支付被拒绝始终会返回结果（CANCELLED 或 FAILED），不会抛出错误。使用 launcher 样式时，验证错误会从 launcher.launch(...) 中抛出。

已放弃的会话

如果应用在结账期间被终止，或用户强制停止应用，SDK 会在本地存储该会话。下次启动应用时，请检查是否存在已放弃的会话，并将其与后端进行协调：

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

abandoned.createdAt 是以毫秒为单位的 epoch 时间戳。

Mobile Integration Guide

移动端结账流程的最佳实践

Kotlin SDK

用于服务端操作的后端 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

安装

使用

结果含义

验证付款

外观自定义

错误

已放弃的会话

相关内容