Android

Đây là Android checkout SDK chính thức (com.dodopayments.api:checkout-android), dùng để mở checkout được lưu trữ của Dodo. SDK này khác với backend Kotlin SDK, vốn gọi Dodo Payments API từ máy chủ của bạn.

Checkout Sessions API

Tạo checkout_url mà SDK này mở

Mobile Integration Guide

Các phương pháp tốt nhất cho quy trình checkout trên thiết bị di động

Android SDK mở checkout được lưu trữ của Dodo trong Chrome Custom Tab bằng androidx.browser.customtabs. SDK không chứa mã networking nào và không lưu API key. Bạn truyền một checkoutUrl từ checkout session ở backend, sau đó SDK trả về một CheckoutResult có kiểu khi người dùng hoàn tất hoặc rời bỏ quy trình. Yêu cầu: minSdk 23, Kotlin, Java 17.

Cài đặt

Add the Dependency

build.gradle.kts

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

Đặt callback scheme của bạn làm Gradle manifest placeholder. Manifest riêng của thư viện đã khai báo intent filter của redirect activity bằng token ${dodoCallbackScheme}, vì vậy thuộc tính này là toàn bộ phần thiết lập — bạn không cần thêm manifest XML nào:

build.gradle.kts

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

Giá trị này phải khớp với scheme trong CheckoutParams.returnUrl (ví dụ: myapp://checkout/return).

Nếu hoàn toàn bỏ qua placeholder, quá trình build sẽ ngay lập tức thất bại với lỗi unresolved-placeholder thay vì âm thầm thất bại tại thời điểm checkout. Nếu bạn đặt giá trị nhưng không khớp với scheme của returnUrl, DodoCheckout.start sẽ ném PLATFORM_ERROR trước khi hiển thị bất kỳ nội dung nào.

Cách sử dụng

SDK hỗ trợ hai kiểu gọi.

Launcher (Recommended)
Suspend Function

Đăng ký contract bằng registerForActivityResult, sau đó khởi chạy 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"
    )
)

Ưu tiên kiểu này. Kết quả được cung cấp thông qua ActivityResultRegistry do hệ điều hành Android quản lý, nên vẫn tồn tại sau khi process bị hủy.

Gọi DodoCheckout.start từ 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()
    }
}

Kiểu này phân giải một CompletableDeferred trong bộ nhớ, vì vậy không tồn tại sau khi process bị hủy. onEvent chỉ khả dụng ở đây, không khả dụng trên contract.

Ý nghĩa của kết quả

Trường status là gợi ý cho UI, không phải bằng chứng thanh toán. Luôn xác minh khoản thanh toán trên backend bằng webhook hoặc endpoint Get Payment Detail trước khi cấp quyền truy cập.

CheckoutStatus

bắt buộc

Một trong các giá trị SUCCEEDED, FAILED, CANCELLED, PENDING, EXPIRED.

String?

Được đặt khi return URL có chứa giá trị này. Hiển thị giá trị trong UI, không dùng giá trị này để cấp quyền truy cập. Xem phần Verify the Payment bên dưới.

String?

Được đặt cho subscription checkout.

List<String>?

Được đặt khi checkout bao gồm các sản phẩm license key.

String?

Được đặt khi checkout thu thập email.

Map<String, String>

Mọi query parameter từ return URL, giữ nguyên văn.

Xác minh khoản thanh toán

Webhooks

Lắng nghe các sự kiện thanh toán theo thời gian thực

Get Payment Detail

Truy vấn trạng thái thanh toán theo yêu cầu

Chỉ cấp quyền truy cập cho người dùng sau khi một trong các cách này xác nhận khoản thanh toán. Không chỉ dựa vào CheckoutResult.status.

Tùy chỉnh giao diện

Tùy chỉnh thanh công cụ, các nút và bảng màu của Custom Tab thông qua customization trên CheckoutParams. Tất cả các trường đều không bắt buộc; nếu bỏ qua customization, giao diện Custom Tab mặc định của Android sẽ được sử dụng.

Màu nền của thanh công cụ, dưới dạng số nguyên ARGB Color.

Màu thanh điều hướng.

Màu đường phân cách phía trên thanh điều hướng.

CloseButtonStyle

DEFAULT hiển thị biểu tượng hệ thống “X”; BACK thay vào đó sẽ vẽ một mũi tên quay lại.

CloseButtonPosition

Vị trí xuất hiện của nút đóng trên thanh công cụ: START hoặc END.

Hiển thị biểu tượng chia sẻ của thanh công cụ.

Boolean

Hiển thị tiêu đề trang bên dưới URL trong thanh công cụ.

Boolean

Cho phép thanh công cụ tự động ẩn khi cuộn trang.

Boolean

Hiển thị “Đánh dấu trang này” trong menu tràn.

Boolean

Hiển thị “Tải trang xuống” trong menu tràn.

ColorScheme

Buộc giao diện sáng hoặc tối bất kể cài đặt hệ thống của thiết bị: SYSTEM, LIGHT hoặc 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,
        )
    )
)

Lỗi

DodoCheckout.start chỉ ném CheckoutError khi sử dụng sai hoặc xảy ra lỗi nền tảng. Đọc mã từ CheckoutError.code:

INVALID_CHECKOUT_URL: không phải là URL phiên checkout.dodopayments.com.
INVALID_RETURN_URL: không phải là URL tuyệt đối hợp lệ.
ALREADY_IN_PROGRESS: một phiên thanh toán đã đang chạy.
PLATFORM_ERROR: lỗi nền tảng không mong đợi, bao gồm returnUrl có scheme không khớp với placeholder dodoCallbackScheme của bạn.

Việc người dùng hủy hoặc khoản thanh toán bị từ chối luôn là một kết quả (CANCELLED hoặc FAILED), không bao giờ là lỗi bị ném. Với kiểu launcher, các lỗi xác thực sẽ được ném ra khỏi launcher.launch(...).

Phiên bị bỏ dở

Nếu ứng dụng bị tắt hoặc người dùng buộc dừng ứng dụng trong quá trình thanh toán, SDK sẽ lưu phiên cục bộ. Ở lần khởi chạy ứng dụng tiếp theo, hãy kiểm tra phiên bị bỏ dở và đối soát phiên đó với backend của bạn:

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

abandoned.createdAt là dấu thời gian epoch tính bằng mili giây.

Liên quan

Mobile Integration Guide

Các phương pháp hay nhất cho quy trình thanh toán trên thiết bị di động

Kotlin SDK

SDK backend cho các thao tác phía máy chủ

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

Cài đặt

Cách sử dụng

Ý nghĩa của kết quả

Xác minh khoản thanh toán

Webhooks

Get Payment Detail

Tùy chỉnh giao diện

Lỗi

Phiên bị bỏ dở

Liên quan

Mobile Integration Guide

Kotlin SDK

Checkout Sessions API

Mobile Integration Guide

​Cài đặt

​Cách sử dụng

​Ý nghĩa của kết quả

​Xác minh khoản thanh toán

Webhooks

Get Payment Detail

​Tùy chỉnh giao diện

​Lỗi

​Phiên bị bỏ dở

​Liên quan

Mobile Integration Guide

Kotlin SDK

Cài đặt

Cách sử dụng

Ý nghĩa của kết quả

Xác minh khoản thanh toán

Tùy chỉnh giao diện

Lỗi

Phiên bị bỏ dở

Liên quan