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 flow의 모범 사례입니다.

Android SDK는 Dodo Payments hosted checkout을 Custom Tab( androidx.browser.customtabs)에서 열고, 고객이 checkout을 완료하거나 나가면 typed CheckoutResult를 반환합니다. 백엔드에서 checkout session을 생성하고 해당 checkout_url를 앱으로 보냅니다. SDK에는 networking code가 없고 API key도 보관하지 않으므로 Dodo Payments API를 직접 호출하지 않습니다. Requirements: minSdk 23, Kotlin, Java 17이 필요합니다. SDK는 androidx.activity, androidx.browser, kotlinx-coroutines-android에만 의존합니다.

설치

Add the Dependency

Maven Central에서 앱 모듈의 build.gradle.kts에 SDK를 추가합니다:

build.gradle.kts

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

Appearance customization에는 version 1.1.0 이상이 필요합니다.

callback scheme을 Gradle manifest placeholder로 설정합니다. SDK 자체의 manifest는 ${dodoCallbackScheme} placeholder를 사용해 redirect activity의 intent filter를 선언하므로, 이 property만 설정하면 됩니다. 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를 생략하면 unresolved-placeholder error와 함께 build가 실패합니다. placeholder가 returnUrl의 scheme과 일치하지 않으면 SDK는 checkout을 열기 전에 PLATFORM_ERROR를 throw합니다.

사용법

SDK에서 checkout을 시작하는 방법은 activity result launcher와 suspend function 두 가지입니다. 둘 다 동일한 CheckoutResult를 반환합니다.

Launcher (Recommended)
Suspend Function

registerForActivityResult에 contract를 등록한 다음 실행합니다:

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를 통해 result를 전달하므로 process death 이후에도 result가 유지됩니다.

coroutine scope에서 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 event를 수신합니다. logging에만 사용하고 outcome을 결정하는 데는 사용하지 마세요.

이 방식은 메모리 내 CompletableDeferred를 기다리므로 result가 process death 이후 유지되지 않습니다. onEvent는 이 방식에서만 사용할 수 있으며 launcher에서는 사용할 수 없습니다.

Result의 의미

SDK는 return URL의 query parameters에서 CheckoutResult를 생성합니다.

status field는 UI hint일 뿐 결제를 증명하지 않습니다. access를 부여하기 전에 webhook 또는 Get Payment Detail endpoint를 사용해 백엔드에서 결제를 확인하세요.

CheckoutStatus

필수

다섯 가지 값 중 하나입니다:

SUCCEEDED: return URL에 status=succeeded(일회성 결제) 또는 status=active(subscription)이 있습니다.
FAILED: 결제가 거절되었습니다(status=failed).
CANCELLED: return URL이 도착하기 전에 고객이 Custom Tab을 닫았습니다. SDK는 outcome을 알 수 없으며 결제가 성공했을 수도 있으므로 failure screen을 표시하지 마세요. 대신 abandoned session을 reconcile하세요.
PENDING: 결제가 나중에 정산됩니다(status=processing 또는 모든 requires_* 값). 또는 status parameter가 없거나 인식되지 않았습니다. CANCELLED와 동일하게 reconcile하세요.
EXPIRED: checkout session이 만료되었습니다(status=expired).

String?

return URL에 payment_id query parameter가 포함된 경우의 값입니다. UI에 표시할 수 있지만 access를 부여하는 데 사용하지 마세요. Verify the Payment을 참조하세요.

String?

subscription_id query parameter입니다. subscription checkout에 설정됩니다.

List<String>?

license_key query parameter입니다. checkout에 license key products가 포함된 경우 설정됩니다.

String?

email query parameter입니다. checkout에서 email address를 수집할 때 설정됩니다.

Map<String, String>

return URL의 모든 query parameter를 있는 그대로 반환합니다.

결제 확인

Webhooks

payment event를 실시간으로 수신합니다.

Get Payment Detail

필요할 때 payment status를 조회합니다.

예를 들어 payment.succeeded 또는 subscription.active webhook을 통해 이 중 하나가 결제를 확인한 후에만 access를 부여하세요. CheckoutResult.status에만 의존하지 마세요.

Appearance Customization

Custom Tab의 toolbar, buttons, color scheme을 변경하려면 CheckoutParams에서 customization로 BrowserCustomization를 전달합니다. 모든 field는 optional이며 기본값은 null입니다. field가 null이면 SDK는 해당 option을 설정하지 않으므로 Custom Tab을 호스팅하는 browser가 자체 기본값을 적용합니다.

toolbar background color를 ARGB Color int로 지정합니다.

navigation bar color를 ARGB Color int로 지정합니다.

navigation bar 위 divider의 color를 ARGB Color int로 지정합니다.

CloseButtonStyle?

DEFAULT는 시스템 “X” icon을 표시합니다. BACK는 SDK가 그리는 back arrow를 표시합니다.

CloseButtonPosition?

close button이 표시되는 toolbar 측면입니다: START 또는 END.

toolbar의 share icon을 표시합니다. false는 이를 숨깁니다.

Boolean?

toolbar의 URL 아래에 page title을 표시합니다.

Boolean?

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

Boolean?

overflow menu에 “Bookmark this page”를 표시합니다.

Boolean?

overflow menu에 “Download page”를 표시합니다.

ColorScheme?

LIGHT 또는 DARK는 기기의 system setting과 관계없이 해당 appearance를 강제합니다. SYSTEM는 system setting을 따릅니다.

이 예제에서는 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,
        )
    )
)

Errors

DodoCheckout.start는 misuse 또는 platform failure의 경우에만 CheckoutError를 throw합니다. CheckoutError.code에서 reason을 확인하세요:

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만 실행할 수 있습니다.
PLATFORM_ERROR: returnUrl scheme이 dodoCallbackScheme placeholder와 일치하지 않는 경우를 포함한 예기치 않은 platform failure입니다.

고객이 취소한 경우나 결제가 거절된 경우는 항상 result(CANCELLED 또는 FAILED)이며, throw된 error가 아닙니다. launcher를 사용하면 validation error는 launcher.launch(...)에서 throw됩니다. launch 이후 발생한 platform failure는 activity result callback을 통해 throw할 수 없으므로 launcher는 raw["error"]에 error code를 담은 CANCELLED를 반환합니다.

Abandoned Sessions

SDK는 checkout이 시작될 때 checkout session을 기록하고, checkout이 SUCCEEDED, FAILED 또는 EXPIRED로 종료될 때만 기록을 삭제합니다. checkout 중 앱이 종료되면 기록이 유지됩니다. 또한 CANCELLED 또는 PENDING result 이후에도 유지됩니다. 이 경우 SDK가 outcome을 알 수 없기 때문입니다. 다음 앱 launch 시와 CANCELLED 또는 PENDING result가 반환될 때마다 이를 확인합니다:

// 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는 cks_로 시작하는 checkout session ID입니다. abandoned.createdAt는 checkout이 시작된 시간이며, milliseconds 단위의 epoch timestamp입니다. 백엔드에서는 Get Checkout Session으로 session을 조회할 수 있으며, 이 endpoint는 해당 session의 payment_id와 payment_status를 반환합니다. 결제가 final status에 도달할 때까지는 failed가 아닌 pending으로 처리하세요.

Mobile Integration Guide

모바일 checkout flow의 모범 사례입니다.

Kotlin SDK

서버 측 작업을 위한 Backend SDK입니다.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

설치

사용법

Result의 의미

결제 확인

Webhooks

Get Payment Detail

Appearance Customization

Errors

Abandoned Sessions

관련 항목

Mobile Integration Guide

Kotlin SDK

Checkout Sessions API

Mobile Integration Guide

​설치

​사용법

​Result의 의미

​결제 확인

Webhooks

Get Payment Detail

​Appearance Customization

​Errors

​Abandoned Sessions

​관련 항목

Mobile Integration Guide

Kotlin SDK

설치

사용법

Result의 의미

결제 확인

Appearance Customization

Errors

Abandoned Sessions

관련 항목