Android

Den här sidan beskriver Android checkout SDK, com.dodopayments.api:checkout-android, som öppnar Dodo Payments hostade checkout i din app. Om du vill anropa Dodo Payments API från din server använder du i stället backend Kotlin SDK.

Checkout Sessions API

Skapa den checkout_url som det här SDK:t öppnar.

Mobile Integration Guide

Bästa praxis för mobila checkout-flöden.

Android SDK öppnar Dodo Payments hostade checkout i en Custom Tab (androidx.browser.customtabs) och returnerar en typad CheckoutResult när kunden slutför eller lämnar checkout. Din backend skapar checkout-sessionen och skickar dess checkout_url till appen. SDK:t innehåller ingen nätverkskod och lagrar ingen API-nyckel, så det anropar aldrig Dodo Payments API. Krav: minSdk 23, Kotlin och Java 17. SDK:t är endast beroende av androidx.activity, androidx.browser och kotlinx-coroutines-android.

Installation

Add the Dependency

Lägg till SDK:t från Maven Central i din appmoduls build.gradle.kts:

build.gradle.kts

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

Anpassning av utseende kräver version 1.1.0 eller senare.

Ange ditt callback-schema som en Gradle manifest placeholder. SDK:t deklarerar själv redirect-aktivitetens intent filter med ${dodoCallbackScheme}-placeholdern i sitt manifest, så den här egenskapen är det enda konfigurationssteget. Du behöver inte lägga till någon manifest-XML:

build.gradle.kts

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

Använd samma schema i CheckoutParams.returnUrl, till exempel myapp://checkout/return, och ange samma URL som checkout-sessionens return_url när din backend skapar sessionen. SDK:t matchar retur-URL:en utifrån schema, host och path och ignorerar query string. URL:en behöver inte läsa in en verklig sida.

Om du utelämnar placeholdern misslyckas bygget med ett unresolved-placeholder-fel. Om placeholdern inte matchar schemat för returnUrl kastar SDK:t PLATFORM_ERROR innan checkout öppnas.

Användning

SDK:t har två sätt att starta checkout: en activity result launcher och en suspend-funktion. Båda returnerar samma CheckoutResult.

Launcher (Recommended)
Suspend Function

Registrera kontraktet med registerForActivityResult och starta det sedan:

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

Använd den här stilen när det är möjligt. Android levererar resultatet via sin ActivityResultRegistry, så resultatet överlever att processen avslutas.

Anropa DodoCheckout.start från en coroutine scope:

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 tar emot händelserna checkout.opened, checkout.return_received och checkout.closed. Använd dem endast för loggning, aldrig för att avgöra resultatet.

Den här stilen väntar på en in-memory CompletableDeferred, så resultatet överlever inte att processen avslutas. onEvent är endast tillgänglig i den här stilen, inte med launchern.

Vad resultatet betyder

SDK:t bygger CheckoutResult från query-parametrarna i retur-URL:en.

Fältet status är en UI-ledtråd, inte ett bevis på betalning. Innan du beviljar åtkomst bekräftar du betalningen på din backend med en webhook eller endpointen Get Payment Detail.

CheckoutStatus

obligatorisk

Ett av fem värden:

SUCCEEDED: retur-URL:en har status=succeeded (engångsbetalning) eller status=active (prenumeration).
FAILED: betalningen nekades (status=failed).
CANCELLED: kunden stängde Custom Tab innan retur-URL:en anlände. SDK:t känner inte till resultatet och betalningen kan ha lyckats, så visa inte en felsida. Stäm i stället av den övergivna sessionen.
PENDING: betalningen slutförs senare (status=processing eller något värde av typen requires_*), eller så saknades parametern status eller kunde inte identifieras. Stäm av den på samma sätt som CANCELLED.
EXPIRED: checkout-sessionen har löpt ut (status=expired).

String?

Query-parametern payment_id, när retur-URL:en innehåller en sådan. Visa den i ditt UI, men använd den inte för att bevilja åtkomst. Se Verifiera betalningen.

String?

Query-parametern subscription_id. Anges för subscription-checkout.

List<String>?

Query-parametern license_key. Anges när checkout innehåller produkter med licensnycklar.

String?

Query-parametern email. Anges när checkout samlar in en e-postadress.

Map<String, String>

Varje query-parameter från retur-URL:en, ordagrant.

Verifiera betalningen

Webhooks

Lyssna på betalningshändelser i realtid.

Get Payment Detail

Fråga efter betalningsstatus på begäran.

Bevilja åtkomst först efter att någon av dessa bekräftar betalningen, till exempel med webhooken payment.succeeded eller subscription.active. Förlita dig inte enbart på CheckoutResult.status.

Anpassa utseendet

Om du vill ändra Custom Tab:s verktygsfält, knappar och färgschema skickar du en BrowserCustomization som customization till CheckoutParams. Alla fält är valfria och har som standard värdet null. För ett null-fält anger SDK:t inte det alternativet, så webbläsaren som hostar Custom Tab använder sitt eget standardvärde.

Bakgrundsfärg för verktygsfältet, som ett ARGB Color-int.

Färg för navigeringsfältet, som ett ARGB Color-int.

Färg på avdelaren ovanför navigeringsfältet, som ett ARGB Color-int.

CloseButtonStyle?

DEFAULT visar systemets “X”-ikon. BACK visar en bakåtpil som SDK:t ritar.

CloseButtonPosition?

Sidan av verktygsfältet där stängningsknappen visas: START eller END.

Visar verktygsfältets delningsikon. false döljer den.

Boolean?

Visar sidans titel under URL:en i verktygsfältet.

Boolean?

Döljer verktygsfältet automatiskt när sidan rullas.

Boolean?

Visar “Bokmärk den här sidan” i overflow-menyn.

Boolean?

Visar “Ladda ner sidan” i overflow-menyn.

ColorScheme?

LIGHT eller DARK tvingar fram det utseendet oavsett enhetens systeminställning. SYSTEM följer systeminställningen.

Det här exemplet återanvänder checkoutLauncher från Användning:

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

Fel

DodoCheckout.start kastar CheckoutError endast vid felaktig användning eller ett plattformsfel. Läs orsaken från CheckoutError.code:

INVALID_CHECKOUT_URL: checkoutUrl är inte en checkout-session-URL för https (path som börjar med /session/) på checkout.dodopayments.com eller test.checkout.dodopayments.com.
INVALID_RETURN_URL: returnUrl är inte en absolut URL med ett schema och en host.
ALREADY_IN_PROGRESS: en annan checkout körs. Endast en checkout kan köras åt gången.
PLATFORM_ERROR: ett oväntat plattformsfel, inklusive ett returnUrl-schema som inte matchar din dodoCallbackScheme-placeholder.

En kund som avbryter, eller en nekad betalning, är alltid ett resultat (CANCELLED eller FAILED), aldrig ett kastat fel. Med launchern kastas valideringsfel från launcher.launch(...). Ett plattformsfel efter starten kan inte kastas genom activity result-callbacken, så launchern returnerar CANCELLED med felkoden i raw["error"].

Övergivna sessioner

SDK:t registrerar checkout-sessionen när checkout startar och rensar posten endast när checkout avslutas med SUCCEEDED, FAILED eller EXPIRED. Posten finns kvar när appen avslutas under checkout och efter resultatet CANCELLED eller PENDING, eftersom SDK:t i dessa fall inte känner till resultatet. Kontrollera om den finns vid nästa appstart och efter varje resultat av typen CANCELLED eller PENDING:

// 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 är checkout-sessionens ID, som börjar med cks_. abandoned.createdAt är tiden då checkout startade, som en epoch-tidsstämpel i millisekunder. Din backend kan slå upp sessionen med Get Checkout Session, som returnerar dess payment_id och payment_status. Tills betalningen når en slutlig status ska du behandla den som väntande, inte misslyckad.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

Installation

Användning

Vad resultatet betyder

Verifiera betalningen

Webhooks

Get Payment Detail

Anpassa utseendet

Fel

Övergivna sessioner

Relaterat

Mobile Integration Guide

Kotlin SDK

Checkout Sessions API

Mobile Integration Guide

​Installation

​Användning

​Vad resultatet betyder

​Verifiera betalningen

Webhooks

Get Payment Detail

​Anpassa utseendet

​Fel

​Övergivna sessioner

​Relaterat

Mobile Integration Guide

Kotlin SDK

Installation

Användning

Vad resultatet betyder

Verifiera betalningen

Anpassa utseendet

Fel

Övergivna sessioner

Relaterat