Android

Dodo의 호스팅 체크아웃을 열기 위한 공식 Android 체크아웃 SDK(com.dodopayments.api:checkout-android)입니다. 서버에서 Dodo Payments API를 호출하는 백엔드 Kotlin SDK와는 별개의 SDK입니다.

Checkout Sessions API

이 SDK가 여는 checkout_url 생성

Mobile Integration Guide

모바일 체크아웃 플로우 모범 사례

Android SDK는 androidx.browser.customtabs를 사용해 Dodo의 호스팅 체크아웃을 Chrome Custom Tab에서 엽니다. 네트워킹 코드가 전혀 포함되어 있지 않으며 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")
}

콜백 스킴을 Gradle manifest placeholder로 설정합니다. 라이브러리 자체의 manifest에는 이미 ${dodoCallbackScheme} 토큰을 사용하는 리디렉션 activity의 intent filter가 선언되어 있으므로, 이 하나의 속성만 설정하면 됩니다. 즉, manifest XML을 직접 추가할 필요가 없습니다:

build.gradle.kts

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

값은 CheckoutParams.returnUrl의 스킴과 일치해야 합니다(예: myapp://checkout/return).

placeholder를 완전히 생략하면 체크아웃 시점에 조용히 실패하는 대신, 해결되지 않은 placeholder 오류와 함께 빌드가 즉시 실패합니다. 설정했지만 returnUrl의 스킴과 일치하지 않으면 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 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는 이 방식에서만 사용할 수 있으며 contract에서는 사용할 수 없습니다.

결과의 의미

status 필드는 결제 증명이 아니라 UI 힌트입니다. 액세스 권한을 부여하기 전에 항상 웹훅 또는 Get Payment Detail endpoint를 사용해 백엔드에서 결제를 확인하세요.

CheckoutStatus

필수

SUCCEEDED, FAILED, CANCELLED, PENDING, EXPIRED 중 하나입니다.

String?

return URL에 하나가 포함되어 있을 때 설정됩니다. UI에 표시하되 액세스 권한을 부여하는 데 사용하지 마세요. 자세한 내용은 아래의 결제 확인을 참조하세요.

String?

subscription 체크아웃에 설정됩니다.

List<String>?

체크아웃에 license key 제품이 포함되어 있을 때 설정됩니다.

String?

체크아웃에서 이메일을 수집할 때 설정됩니다.

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: 체크아웃이 이미 실행 중입니다.
PLATFORM_ERROR: dodoCallbackScheme placeholder와 스킴이 일치하지 않는 returnUrl를 포함한 예기치 않은 플랫폼 오류입니다.

사용자가 취소하거나 결제가 거부된 경우에는 항상 결과(CANCELLED 또는 FAILED)가 반환되며, 오류가 발생하지 않습니다. launcher 방식에서는 유효성 검사 오류가 launcher.launch(...) 밖으로 throw됩니다.

중단된 세션

체크아웃 중 앱이 종료되거나 사용자가 앱을 강제 종료하면 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

서버 측 작업을 위한 백엔드 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

설치

사용법

결과의 의미

결제 확인

오류

중단된 세션

관련 항목