Android

This is the official Android checkout SDK (com.dodopayments.api:checkout-android), for opening Dodo’s hosted checkout. It is distinct from the backend Kotlin SDK, which calls the Dodo Payments API from your server.

Checkout Sessions API

Create the checkout_url that this SDK opens

Mobile Integration Guide

Best practices for mobile checkout flows

The Android SDK opens Dodo’s hosted checkout in a Chrome Custom Tab using androidx.browser.customtabs. It contains zero networking code and holds no API key. You pass a checkoutUrl from your backend’s checkout session, and the SDK returns a typed CheckoutResult when the user completes or abandons the flow. Requirements: minSdk 23, Kotlin, Java 17.

Installation

Add the Dependency

build.gradle.kts

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

Set your callback scheme as a Gradle manifest placeholder. The library’s own manifest already declares the redirect activity’s intent filter using the ${dodoCallbackScheme} token, so this one property is the entire setup cost — you add no manifest XML:

build.gradle.kts

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

The value must match the scheme in CheckoutParams.returnUrl (e.g. myapp://checkout/return).

If you omit the placeholder entirely, the build fails immediately with an unresolved-placeholder error rather than failing silently at checkout time. If you set it but it doesn’t match returnUrl’s scheme, DodoCheckout.start throws PLATFORM_ERROR before presenting anything.

Usage

The SDK supports two invocation styles.

Launcher (Recommended)
Suspend Function

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

Prefer this style. The result is delivered through Android’s OS-managed ActivityResultRegistry, so it survives process death.

Call DodoCheckout.start from a coroutine scope:

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

This style resolves an in-memory CompletableDeferred, so it does not survive process death. onEvent is available only here, not on the contract.

What the Result Means

The status field is a UI hint, not proof of payment. Always verify the payment on your backend using webhooks or the Get Payment Detail endpoint before granting access.

CheckoutStatus

required

One of SUCCEEDED, FAILED, CANCELLED, PENDING, EXPIRED.

String?

Set when the return URL included one. Display it in the UI, don’t use it to grant access. See Verify the Payment below.

String?

Set for subscription checkouts.

List<String>?

Set when the checkout includes license key products.

String?

Set when the checkout captures an email.

Map<String, String>

Every query parameter from the return URL, verbatim.

Verify the Payment

Webhooks

Listen for payment events in real time

Get Payment Detail

Query the payment status on demand

Grant access to the user only after one of these confirms the payment. Do not rely on the CheckoutResult.status alone.

Errors

DodoCheckout.start throws CheckoutError only for misuse or a platform failure. Read the code from CheckoutError.code:

INVALID_CHECKOUT_URL: not a checkout.dodopayments.com session URL.
INVALID_RETURN_URL: not a valid absolute URL.
ALREADY_IN_PROGRESS: a checkout is already running.
PLATFORM_ERROR: unexpected platform failure, including a returnUrl whose scheme doesn’t match your dodoCallbackScheme placeholder.

A user cancelling or a declined payment is always a result (CANCELLED or FAILED), never a thrown error. With the launcher style, validation errors throw out of launcher.launch(...).

Abandoned Sessions

If the app is killed or the user force-stops it during checkout, the SDK stores the session locally. On the next app launch, check for an abandoned session and reconcile it with your backend:

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

The abandoned.createdAt is an epoch timestamp in milliseconds.

Mobile Integration Guide

Best practices for mobile checkout flows

Kotlin SDK

Backend SDK for server-side operations

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

Installation

Usage

What the Result Means

Verify the Payment

Webhooks

Get Payment Detail

Errors

Abandoned Sessions

Mobile Integration Guide

Kotlin SDK

Checkout Sessions API

Mobile Integration Guide

​Installation

​Usage

​What the Result Means

​Verify the Payment

Webhooks

Get Payment Detail

​Errors

​Abandoned Sessions

​Related

Mobile Integration Guide

Kotlin SDK

Installation

Usage

What the Result Means

Verify the Payment

Errors

Abandoned Sessions

Related