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만 신뢰하지 마세요.

Appearance Customization

customization에서 CheckoutParams을 통해 Custom Tab의 toolbar, 버튼 및 색 구성표를 맞춤설정할 수 있습니다. 모든 필드는 선택 사항이며, customization을 생략하면 Android의 기본 Custom Tab appearance가 사용됩니다.

Toolbar background color, as an ARGB Color int.

Navigation bar color.

Divider color above the navigation bar.

CloseButtonStyle

DEFAULT은 시스템 “X” 아이콘을 표시하고, BACK은 대신 뒤로 가기 화살표를 그립니다.

CloseButtonPosition

닫기 버튼이 toolbar의 어느 쪽에 표시될지 지정합니다: START 또는 END.

toolbar의 공유 아이콘을 표시합니다.

Boolean

toolbar에서 URL 아래에 페이지 제목을 표시합니다.

Boolean

페이지를 스크롤할 때 toolbar를 자동으로 숨깁니다.

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

Errors

DodoCheckout.start은 잘못된 사용 또는 플랫폼 오류가 발생한 경우에만 CheckoutError을 throw합니다. CheckoutError.code에서 코드를 확인하세요:

INVALID_CHECKOUT_URL: checkout.dodopayments.com 세션 URL이 아닙니다.
INVALID_RETURN_URL: 유효한 절대 URL이 아닙니다.
ALREADY_IN_PROGRESS: checkout이 이미 실행 중입니다.
PLATFORM_ERROR: 예기치 않은 플랫폼 오류입니다. 여기에는 dodoCallbackScheme placeholder와 scheme이 일치하지 않는 returnUrl도 포함됩니다.

사용자가 취소하거나 결제가 거부된 경우에는 항상 결과(CANCELLED 또는 FAILED)로 반환되며, throw된 오류가 아닙니다. launcher style을 사용하면 validation 오류가 launcher.launch(...) 밖으로 throw됩니다.

Abandoned Sessions

checkout 중 앱이 종료되거나 사용자가 앱을 강제 종료하면 SDK가 세션을 로컬에 저장합니다. 다음에 앱이 실행될 때 abandoned session이 있는지 확인하고 이를 backend와 대조하여 처리하세요:

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

abandoned.createdAt은 밀리초 단위의 epoch timestamp입니다.

Mobile Integration Guide

모바일 checkout flow의 모범 사례

Kotlin SDK

서버 측 작업을 위한 Backend SDK

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

설치

사용법

결과의 의미

결제 확인

Webhooks

Get Payment Detail

Appearance Customization

Errors

Abandoned Sessions

Mobile Integration Guide

Kotlin SDK

Checkout Sessions API

Mobile Integration Guide

​설치

​사용법

​결과의 의미

​결제 확인

Webhooks

Get Payment Detail

​Appearance Customization

​Errors

​Abandoned Sessions

​Related

Mobile Integration Guide

Kotlin SDK

설치

사용법

결과의 의미

결제 확인

Appearance Customization

Errors

Abandoned Sessions

Related