Abonnement-Integration erstellen

Das Stripe Android SDK ist Open Source und vollständig dokumentiert.

Um das SDK zu installieren, fügen Sie stripe-android in den Block dependencies Ihrer app/build.gradle-Datei ein:

plugins {
    id("com.android.application")
}

android { ... }

dependencies {
  // ...

  // Stripe Android SDK
  implementation("com.stripe:stripe-android:21.17.0")
  // Include the financial connections SDK to support US bank account as a payment method
  implementation("com.stripe:financial-connections:21.17.0")
}

Konfigurieren Sie das SDK mit Ihrem veröffentlichbaren Schlüssel von Stripe so, dass dieser Anfragen an die API stellen kann, wie beispielsweise in Ihrer Unterklasse Application:

import com.stripe.android.PaymentConfiguration

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        PaymentConfiguration.init(
            applicationContext,
            
"pk_test_TYooMQauvdEDq54NiTphI7jx"
        )
    }
}

Installieren Sie dann die Stripe-CLI. Mit der Stripe-CLI können Sie Webhooks testen und Stripe-APIs aufrufen. In einem späteren Abschnitt dieses Leitfadens wird erklärt, wie Sie mithilfe der CLI ein Preismodell einrichten können.

# Install Homebrew to run this command: https://brew.sh/
brew install stripe/stripe-cli/stripe

# Connect the CLI to your dashboard
stripe login

Weitere Installationsoptionen finden Sie unter Mit der Stripe-CLI loslegen.

Erstellen Sie Ihre Produkte und die zugehörigen Preise im Dashboard oder mit der Stripe-CLI.

In diesem Beispiel wird ein Festpreisdienst mit zwei verschiedenen Service-Level-Optionen verwendet: Basic und Premium. Für jede Service-Level-Option müssen Sie ein Produkt und einen wiederkehrenden Preis erstellen. (Wenn Sie eine einmalige Gebühr, z. B. für die Einrichtung, hinzufügen möchten, erstellen Sie ein drittes Produkt mit einem einmaligen Preis. Der Einfachheit halber verzichtet dieses Beispiel auf eine einmalige Gebühr).

In diesem Beispiel wird jedes Produkt in monatlichen Intervallen abgerechnet. Der Preis für das Basic-Produkt beträgt 5 USD. Der Preis für das Premium-Produkt beträgt 15 USD.

Stripe benötigt für jedes Abonnement eine/einen Kundin/Kunden. Erfassen Sie im Frontend Ihrer Anwendung alle von den Nutzerinnen/Nutzern benötigten Informationen und übergeben Sie diese ans Backend.

Möglicherweise möchten Sie eine Netzwerkbibliothek verwenden, um Netzwerkanforderungen an Ihr Backend zu senden. Dieses Dokument verwendet okhttp, Sie können jedoch jede mit Ihrem Projekt kompatible Bibliothek nutzen.

dependencies {
  ...
  implementation "com.squareup.okhttp3:okhttp:4.12.0"
}

Wenn Sie Adressdaten erfassen müssen, können Sie mit dem Address Element Versand- und Rechnungsadressen Ihrer Kundinnen/Kunden erfassen. Weitere Informationen zu dem Thema finden Sie auf der Seite Address Element.

import androidx.compose.foundation.layout.Column
import androidx.compose.material3.Button
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody
import org.json.JSONObject

@Composable
fun RegisterView() {
    var email by remember { mutableStateOf("") }
    Column {
        OutlinedTextField(value = email,
            label = { Text(text = "Email") },
            onValueChange = { email = it })
        Button(onClick = {
            val body = JSONObject().put("email", email).toString()
                .toRequestBody("application/json".toMediaType())
            val request =
                Request.Builder().url("http://10.0.2.2:4567/create-customer").post(body).build()
            CoroutineScope(Dispatchers.IO).launch {
                OkHttpClient().newCall(request).execute().use { response ->
                    if (response.isSuccessful) {
                        println(JSONObject(response.body!!.string()).get("customer"))
                    }
                }
            }
        }) {
            Text(text = "Submit")
        }
    }
}

Erstellen Sie das Stripe Customer-Objekt auf dem Server.

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d email={{CUSTOMER_EMAIL}} \
  -d name={{CUSTOMER_NAME}} \
  -d "shipping[address][city]"=Brothers \
  -d "shipping[address][country]"=US \
  -d "shipping[address][line1]"="27 Fredrick Ave" \
  -d "shipping[address][postal_code]"=97712 \
  -d "shipping[address][state]"=CA \
  -d "shipping[name]"={{CUSTOMER_NAME}} \
  -d "address[city]"=Brothers \
  -d "address[country]"=US \
  -d "address[line1]"="27 Fredrick Ave" \
  -d "address[postal_code]"=97712 \
  -d "address[state]"=CA

Lassen Sie neuen Kundinnen und Kunden einen Plan auswählen und dann ein Abonnement erstellen. In diesem Leitfaden stehen einen Basic- und ein Premium-Plan zur Auswahl.

Übergeben Sie in Ihrer App die ausgewählte Preis-ID und die ID des Kundendatensatzes an das Backend.

import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody
import org.json.JSONObject

fun createSubscription(priceId: String, customerId: String): SubscriptionResponse? {
    val body = JSONObject()
        .put("priceId", priceId)
        .put("customerId", customerId).toString()
        .toRequestBody("application/json".toMediaType())
    val request =
        Request.Builder().url("http://10.0.2.2:4567/create-subscription").post(body).build()
    OkHttpClient().newCall(request).execute().use { response ->
        if (response.isSuccessful) {
            // SubscriptionsResponse is data class conforming to the expected response from your backend.
            // It should include the client_secret, as discussed below.
            return Gson().fromJson(response.body!!.string(), SubscriptionResponse::class.java)
        }
    }
    return null
}

Erstellen Sie im Backend mithilfe von payment_behavior=default_incomplete das Abonnement mit dem Status incomplete. Geben Sie dann das client_secret aus dem ersten Payment Intent des Abonnements an das Frontend zurück, um die Zahlung abzuschließen, indem Sie das confirmation_secret auf der letzten Rechnung des Abonnements erweitern.

Legen Sie save_default_payment_method auf on_subscription fest, um die Zahlungsmethode bei erfolgreicher Zahlung als Standard für ein Abonnement zu speichern. Das Speichern einer Standardzahlungsmethode erhöht die Erfolgsquote künftiger Abonnementzahlungen.

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

post '/create-subscription' do
  content_type 'application/json'
  data = JSON.parse(request.body.read)
  customer_id = cookies[:customer]
  price_id = data['priceId']

  # Create the subscription. Note we're expanding the Subscription's
  # latest invoice and that invoice's confirmation_secret
  # so we can pass it to the front end to confirm the payment
  subscription = Stripe::Subscription.create(
    customer: customer_id,
    items: [{
      price: price_id,
    }],
    payment_behavior: 'default_incomplete',
    payment_settings: {save_default_payment_method: 'on_subscription'},
    expand: ['latest_invoice.confirmation_secret']
  )

  { subscriptionId: subscription.id, clientSecret: subscription.latest_invoice.confirmation_secret.client_secret }.to_json
end

An dieser Stelle ist das Abonnement inactive und wartet auf die Zahlung. Nachfolgend finden Sie eine Beispielantwort. Die zum Speichern erforderlichen Felder sind hervorgehoben. Sie sollten jedoch alle Felder speichern, auf die Ihre Anwendung häufig zugreift.

{
  "id": "sub_JgRjFjhKbtD2qz",
  "object": "subscription",
  "application_fee_percent": null,
  "automatic_tax": {
    "disabled_reason": null,
    "enabled": false,
    "liability": "null"
  },
  "billing_cycle_anchor": 1623873347,

Verwenden Sie das Mobile Payment Element, um Zahlungsdetails zu erfassen und das Abonnement zu aktivieren. Sie können Elements an das Erscheinungsbild Ihrer Anwendung anpassen.

Das Mobile Payment Element erfasst sicher alle notwendigen Zahlungsdaten für eine Vielzahl von Zahlungsmethoden. Erfahren Sie mehr über die unterstützten Zahlungsmethoden für Mobile Payment Element und Abonnements.

Payment Element zu Ihrer App hinzufügen

Initialisieren und präsentieren Sie das Mobile Payment Element mit der PaymentSheet-Klasse.

import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import com.stripe.android.paymentsheet.PaymentSheet
import com.stripe.android.paymentsheet.PaymentSheetResult
import com.stripe.android.paymentsheet.rememberPaymentSheet

@Composable
fun SubscribeView(clientSecret: String) {
    val paymentSheet = rememberPaymentSheet(::onPaymentSheetResult)

    Button(onClick = {
        paymentSheet.presentWithPaymentIntent(
            clientSecret, PaymentSheet.Configuration(
                primaryButtonLabel = "Subscribe for $15/month",
                merchantDisplayName = "My merchant name",
                // Set `allowsDelayedPaymentMethods` to true if your business handles
                // delayed notification payment methods like US bank accounts.
                allowsDelayedPaymentMethods = true
            )
        )
    }) {
        Text(text = "Subscribe")
    }
}

fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) {
    when (paymentSheetResult) {
        is PaymentSheetResult.Canceled -> {
            print("Canceled")
        }

        is PaymentSheetResult.Failed -> {
            print("Error: ${paymentSheetResult.error}")
        }

        is PaymentSheetResult.Completed -> {
            // Display for example, an order confirmation screen
            print("Completed")
        }
    }
}

Das Mobile Payment Element stellt ein Formular dar, mit dem Ihre Kundinnen und Kunden eine Zahlungsmethode auswählen können. Das Formular erfasst automatisch alle notwendigen Zahlungsdetails für die ausgewählte Zahlungsmethode.

Wenn Sie allowsDelayedPaymentMethods auf true festlegen, werden Zahlungsmethoden mit verzögerter Benachrichtigung wie US-Bankkonten zugelassen. Für diese Zahlungsmethoden ist der endgültige Zahlungsstatus nicht bekannt, wenn das PaymentSheet abgeschlossen wird. Stattdessen ist sie erfolgreich oder schlägt fehl. Wenn Sie diese Art von Zahlungsmethoden unterstützen, informieren Sie den Kunden/die Kundin darüber, dass seine/ihre Bestellung bestätigt ist, und führen seine/ihre Bestellung erst aus (z. B. das Produkt versenden), wenn die Zahlung erfolgreich ist.

Sie können das Payment Element an das Design Ihrer App anpassen, indem Sie für Ihr PaymentSheet.Configuration-Objekt die appearance-Eigenschaft verwenden.

Zahlung bestätigen

Das Mobile Payment Element erstellt eine PaymentMethod und bestätigt den ersten PaymentIntent des unvollständigen Abonnements, wodurch eine Zahlung ausgeführt wird. Wenn die Zahlung die starke Kundenauthentifizierung (SCA) erfordert, übernimmt das Payment Element den Authentifizierungsprozess, bevor der PaymentIntent bestätigt wird.

Um Ihre Integration abzuschließen, müssen Sie von Stripe gesendete Webhooks verarbeiten. Dies sind Ereignisse, die ausgelöst werden, wenn sich ein Status innerhalb von Stripe ändert, z. B. wenn Abonnements neue Rechnungen erstellen. Richten Sie in Ihrer Anwendung einen HTTP-Handler ein, um eine POST-Anfrage mit dem Webhook-Ereignis zu akzeptieren und verifizieren Sie die Signatur des Ereignisses.

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

post '/webhook' do
  # You can use webhooks to receive information about asynchronous payment events.
  # For more about our webhook events check out https://stripe.com/docs/webhooks.
  webhook_secret = ENV['STRIPE_WEBHOOK_SECRET']
  payload = request.body.read
  if !webhook_secret.empty?

Verwenden Sie während der Entwicklung die Stripe-CLI, um Webhooks zu beobachten und an Ihre Anwendung weiterzuleiten. Führen Sie Folgendes in einem neuen Datenterminal aus, während Ihre Entwicklungs-App ausgeführt wird:

stripe listen --forward-to localhost:4242/webhook

Für die Produktionsphase können Sie eine Webhook-Endpoint-URL über das Dashboard oder mit der Webhook Endpoints API einrichten.

Um die verbleibenden Schritte dieses Leitfadens abzuschließen, müssen Sie einige Ereignisse überwachen. Weitere Details zu Abonnement-spezifischen Webhooks finden Sie unter Abonnement-Ereignisse.

Nachdem das Abonnement nun aktiv ist, gewähren Sie Ihren Nutzern und Nutzerinnen Zugriff auf Ihre Dienstleistung. Überwachen Sie dazu die Ereignisse customer.subscription.created, customer.subscription.updated und customer.subscription.deleted. Diese Ereignisse übergeben ein Abonnementobjekt, das ein status-Feld enthält, das anzeigt, ob das Abonnement aktiv oder überfällig ist oder gekündigt wurde. Eine vollständige Statusliste finden Sie unter Abonnementlebenszyklus.

In Ihrem Webhook-Handler:

1. Überprüfen Sie den Abonnementstatus. Wenn er active ist, hat Ihre Nutzerin/Ihr Nutzer für Ihr Produkt bezahlt.
2. Überprüfen Sie das Produkt, das die Kundin/der Kunde abonniert hat, und gewähren Sie Zugang zu Ihrer Dienstleistung. Bei der Überprüfung des Produkts sind Sie im Vergleich zur Überprüfung des Preises flexibler, falls Sie den Preis oder das Abrechnungsintervall ändern müssen.
3. Speichern Sie die product.id, subscription.id und den subscription.status in Ihrer Datenbank zusammen mit der bereits gespeicherten customer.id. Überprüfen Sie diesen Datensatz, wenn Sie entscheiden, welche Funktionen für die Nutzer/innen Ihrer Anwendung aktiviert werden sollen.

Der Status eines Abonnements kann sich während seiner Laufzeit jederzeit ändern, auch wenn Ihre Anwendung Stripe nicht direkt aufruft. Beispielsweise kann eine Verlängerung aufgrund einer abgelaufenen Kreditkarte fehlschlagen, wodurch das Abonnement in einen überfälligen Status versetzt wird. Oder wenn Sie das Kundenportal implementieren, können Nutzer/innen ihr Abonnement kündigen, ohne Ihre Anwendung direkt aufzurufen. Durch die korrekte Implementierung Ihres Handlers wird der Anwendungsstatus mit Stripe synchronisiert.

Es ist gängige Praxis, dass Kundinnen/Kunden ihr Abonnement selbst kündigen können. In diesem Beispiel wird zur Seite mit den Kontoeinstellungen eine Kündigungsoption hinzugefügt.

In diesem Beispiel wird die Abonnement-ID im Frontend erfasst. Im Produktionsbetrieb kann Ihre Anwendung diese Information für Ihre angemeldeten Nutzer/innen aus Ihrer Datenbank abrufen.

Kontoeinstellungen mit der Option, das Abonnement zu kündigen

fun cancelSubscription(subscriptionId: String): SubscriptionResponse? {
    val body = JSONObject().put("subscriptionId", subscriptionId).toString()
        .toRequestBody("application/json".toMediaType())
    val request =
        Request.Builder().url("http://10.0.2.2:4567/cancel-subscription").post(body).build()
    OkHttpClient().newCall(request).execute().use { response ->
        if (response.isSuccessful) {
            return Gson().fromJson(response.body!!.string(), SubscriptionResponse::class.java)
        }
    }
    return null
}

Definieren Sie im Backend den Endpoint für den Aufruf durch Ihre App.

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

post '/cancel-subscription' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  deleted_subscription = Stripe::Subscription.cancel(data['subscriptionId'])

  deleted_subscription.to_json
end

Ihr Backend erhält ein Ereignis vom Typ customer.subscription.deleted.

Aktualisieren Sie nach der Kündigung des Abonnements Ihre Datenbank, um die zuvor gespeicherte Stripe-Abonnement-ID zu entfernen, und schränken Sie den Zugang zu Ihrer Dienstleistung ein.

Wenn ein Abonnement gekündigt wurde, kann es nicht reaktiviert werden. Sie müssen stattdessen die aktualisierten Rechnungsinformationen von Ihrer Kundinnen/Kunden erfassen, deren Standard-Zahlungsmethode aktualisieren und ein neues Abonnement für den bestehenden Kundendatensatz erstellen.

Zahlungsmethoden testen

Verwenden Sie die folgende Tabelle, um verschiedene Zahlungsmethoden und -szenarien zu testen.

Ereignisse überwachen

Richten Sie Webhooks ein, um Abonnementänderungsereignisse wie Upgrades und Kündigungen zu überwachen. Erfahren Sie mehr über Abonnement-Webhooks. Sie können Ereignisse im Dashboard oder mit der Stripe-CLI anzeigen.

Weitere Informationen finden Sie unter Billing-Integration testen.