Zukünftige Kartenzahlungen einrichten

Zunächst benötigen Sie ein Stripe-Konto. Jetzt registrieren.

Serverseitig

Diese Integration erfordert Endpoints auf Ihrem Server, die mit der Stripe-API kommunizieren können. Nutzen Sie unsere offiziellen Bibliotheken für den Zugriff auf die Stripe-API von Ihrem Server aus:

# Available as a gem
sudo gem install stripe

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Clientseitig

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

To install the SDK, add stripe-android to the dependencies block of your app/build.gradle file:

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

android { ... }

dependencies {
  // ...

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

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

Um eine Karte für zukünftige Zahlungen einzurichten, müssen Sie sie einem/einer Kund/in hinzufügen. Erstellen Sie ein Customer-Objekt, wenn Ihr/e Kund/in ein Konto bei Ihrem Unternehmen erstellt. Customer-Objekte ermöglichen die Wiederverwendung von Zahlungsmethoden und die Nachverfolgung über mehrere Zahlungen hinweg.

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d name="Jenny Rosen" \
  --data-urlencode email="jennyrosen@example.com"

Bei erfolgreicher Erstellung wird das Kundenobjekt zurückgegeben. Sie können das Objekt bezüglich der Kunden-id überprüfen and den Wert zum späteren Abruf in Ihrer Datenbank speichern.

Sie finden diese Kundinnen/Kunden auf der Seite Kundinnen/Kunden im Dashboard.

Ein SetupIntent ist ein Objekt, mit dem Sie eine Zahlungsmethode für zukünftige Zahlungen einrichten können.

Das SetupIntent-Objekt enthält ein Client-Geheimnis, also einen eindeutigen Schlüssel, den Sie an Ihre App übergeben. Mit dem Client-Geheimnis können Sie bestimmte Aktionen auf dem Client durchführen (z. B. die Einrichtung bestätigen und Details zur Zahlungsmethode ändern) und dabei gleichzeitig sensible Informationen wie customer verbergen. Außerdem können Sie mit dem Client-Geheimnis Kartenangaben bei den Kreditkartennetzwerken validieren und authentifizieren. Das Client-Geheimnis ist vertraulich – protokollieren Sie es nicht, betten Sie es nicht in URLs ein und geben Sie es nicht an andere Personen als die Kundin/den Kunden weiter.

Serverseitig

Erstellen Sie auf Ihrem Server einen Endpoint, der einen SetupIntent erstellt und dessen Client-Geheimnis an Ihre App zurückgibt.

curl https://api.stripe.com/v1/setup_intents/ \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "customer"="{{CUSTOMER_ID}}"

If you only plan on using the card for future payments when your customer is present during the checkout flow, set the usage parameter to on_session to improve authorization rates.

Clientseitig

Fordern Sie auf dem Client einen SetupIntent von Ihrem Server an.

class CheckoutActivity : AppCompatActivity() {
   private lateinit var setupIntentClientSecret: String

   private fun loadPage() {
       // Request a SetupIntent from your server and store its client secret
       // Click View full sample to see a complete implementation
   }
}

Wenn der/die Kund/in das Zahlungsformular übermittelt, können Sie seine/ihre Kartendaten mit CardInputWidget erfassen. Hierbei handelt es sich um eine Drop-In-Komponente der Nutzeroberfläche aus dem SDK, die die Kartennummer, das Ablaufdatum, die Prüfziffer (CVC) und die Postleitzahl erfasst.

Rufen Sie die Methode getPaymentMethodCard auf, um die Kartenangaben abzurufen. Übergeben Sie die erfassten Informationen an die neuen Instanzen PaymentMethodCreateParams und PaymentMethod.BillingDetails, um eine ConfirmSetupIntentParams-Instanz zu erstellen.

// Collect card details
val cardInputWidget =
    findViewById<CardInputWidget>(R.id.cardInputWidget)
val paymentMethodCard = cardInputWidget.paymentMethodCard

// Later, you will need to attach the PaymentMethod to the Customer it belongs to.
// This example collects the customer's email to know which customer the PaymentMethod belongs to, but your app might use an account id, session cookie, and so on.
val emailInput = findViewById<EditText>(R.id.emailInput)
val billingDetails = PaymentMethod.BillingDetails.Builder()
    .setEmail((emailInput.text ?: "").toString())
    .build()

// Create SetupIntent confirm parameters with the above
if (paymentMethodCard != null) {
    val paymentMethodParams = PaymentMethodCreateParams
        .create(paymentMethodCard, billingDetails, null)
    val confirmParams = ConfirmSetupIntentParams
        .create(paymentMethodParams, setupIntentClientSecret)
    lifecycleScope.launch {
        paymentLauncher.confirm(confirmParams)
    }
}

Zum Abschließen der Einrichtung übergeben Sie das SetupIntentParams-Objekt mit der aktuellen Aktivität an PaymentLauncher confirm. Mit dem SetupIntent wird geprüft, ob die Karteninformationen Ihres/Ihrer Kund/in im Netzwerk gültig sind. Die automatische Überprüfung wird jedoch nicht immer durchgeführt. Einzelheiten hierzu finden Sie unter Ohne Abbuchung prüfen, ob eine Karte gültig ist. Von der Nutzung von dauerhaften, nicht regelmäßig gepflegten SetupIntents wird außerdem abgeraten, da diese möglicherweise nicht mehr gültig sind, wenn Sie PaymentLauncher#confirm() aufrufen.

Bei manchen Zahlungsmethoden sind für den Abschluss der Zahlung zusätzliche Authentifizierungsschritte erforderlich. Das SDK verwaltet die Zahlungsbestätigung und den Authentifizierungsablauf, was das Einblenden zusätzlicher Bildschirme beinhalten kann, die für die Authentifizierung erforderlich sind. Weitere Informationen zur 3D Secure-Authentifizierung und zur Anpassung des Authentifizierungsprozesses finden Sie unter Unterstützung der 3D Secure-Authentifizierung auf Android.

Das Ergebnis des Ablaufs leitet Sie zu Ihrer über den Rückruf bereitgestellten aufrufenden Aktivität, hier onPaymentResult, zurück. Das vom PaymentLauncher zurückgegebene PaymentResult hat folgende Typen:

• Completed: Bestätigung oder Authentifizierung erfolgreich
• Canceled: Kund/in hat die erforderliche Authentifizierung abgebrochen
• Failed: Der Authentifizierungsversuch ist fehlgeschlagen, ein Grund wird von throwable angegeben

private fun onPaymentResult(paymentResult: PaymentResult) {
    var title = ""
    var message = ""
    var restartDemo = false
    when (paymentResult) {
        is PaymentResult.Completed -> {
            title = "Setup Completed"
            restartDemo = true
        }
        is PaymentResult.Canceled -> {
            title = "Setup Canceled"
        }
        is PaymentResult.Failed -> {
            title = "Setup Failed"
            message = paymentResult.throwable.message!!
        }
    }
    displayAlert(title, message, restartDemo)
}

Sie haben jetzt einen Ablauf erstellt, um Kartenangaben zu erfassen und Authentifizierungsanfragen zu verarbeiten. Verwenden Sie die Testkarte 4000 0025 0000 3155 mit einer beliebigen Prüfziffer (CVC) und Postleitzahl und einem beliebigen Ablaufdatum, um den Authentifizierungsprozess zu testen.

Wenn der SetupIntent erfolgreich war, wird die sich daraus ergebene PaymentMethod-ID (in setupIntent.getPaymentMethodId()) im bereitgestellten Customer-Objekt gespeichert.

Wenn Sie eine Off-Session-Belastung eines Kundenkontos vornehmen möchten, erstellen Sie anhand der Kunden-ID und der PaymentMethod-ID einen PaymentIntent. Um eine belastbare Karte zu finden, lassen Sie sich die mit Ihren Kundinnen/Kunden verknüpften PaymentMethods auflisten auflisten.

curl -G https://api.stripe.com/v1/payment_methods \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d type=card

Wenn Ihnen die Kunden-ID und die PaymentMethod-ID vorliegen, erstellen Sie eine PaymentIntent mit dem Betrag und der Währung der Zahlung. Legen Sie einige weitere Parameter fest, um die Off-Session-Zahlung durchzuführen:

• Setzen Sie off_session auf true, um anzugeben, dass sich der Kunde/die Kundin während dieses Zahlungsversuchs nicht in Ihrem Bezahlvorgang befindet. Dies hat zur Folge, dass der PaymentIntent einen Fehler ausgibt, wenn eine Authentifizierung erforderlich ist.
• Legen Sie den Wert der Eigenschaft confirm des PaymentIntent auf true fest. Dadurch erfolgt die Bestätigung sofort, wenn der PaymentIntent erstellt wird.
• Setzen Sie payment_method auf die ID der PaymentMethod und Kunde/Kundin auf die ID des Kunden/der Kundin.

curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d amount=1099 \
  -d currency=usd \
  -d customer="{{CUSTOMER_ID}}" \
  -d payment_method="{{PAYMENT_METHOD_ID}}" \
  -d off_session=true \
  -d confirm=true

Überprüfen Sie die Status-Eigenschaft des PaymentIntent, um zu bestätigen, dass die Zahlung erfolgreich durchgeführt wurde. Wenn der Zahlungsversuch erfolgreich war, ist der Status des PaymentIntent succeeded, und die Off-Session-Zahlung ist abgeschlossen.

Wiederherstellungsablauf starten

Falls der PaymentIntent einen anderen Status hat, wurde die Zahlung nicht erfolgreich durchgeführt, und die Anfrage schlägt fehl. Bitten Sie Ihre Kund/innen, zu Ihrer Anwendung zurückzukehren (zum Beispiel per E-Mail, Textnachricht, Push-Benachrichtigung), um die Zahlung abzuschließen. Wir empfehlen, in Ihrer App einen Wiederherstellungsablauf zu erstellen, der zeigt, warum die Zahlung zuerst nicht durchgeführt werden konnte, und Ihre Kund/innen einen erneuten Versuch unternehmen lässt.

In your recovery flow, retrieve the PaymentIntent through its client secret. Check the PaymentIntent’s lastPaymentError to inspect why the payment attempt failed. For card errors, you can show the user the last payment error’s message. Otherwise, you can show a generic failure message.

fun startRecoveryFlow(clientSecret: String) {
    val stripe = Stripe(
        applicationContext,
        PaymentConfiguration.getInstance(applicationContext).publishableKey
    )
    lifecycleScope.launch {
        runCatching {
            stripe.retrievePaymentIntent(clientSecret)
        }.fold(
            onSuccess = { paymentIntent ->
                var failureReason =
                    "Payment failed, try again" // Default to a generic error message
                paymentIntent.lastPaymentError?.let { lastPaymentError ->
                    if (lastPaymentError.type == PaymentIntent.Error.Type.CardError) {
                        lastPaymentError.message?.let { errorMessage ->
                            failureReason = errorMessage
                            // Display the failure reason to your customer
                        }
                    }
                }
            },
            onFailure = {
                // Handle error
            }
        )
    }
}

Lassen Sie es Ihre Kunden erneut versuchen

Geben Sie Kundinnen und Kunden die Möglichkeit, ihre gespeicherten Karten zu aktualisieren oder zu entfernen. Führen Sie dann die Zahlung in Ihrem Wiederherstellungsverfahren erneut durch. Gehen Sie dabei genauso vor wie bei der Annahme der ersten Zahlung, mit einem Unterschied: Bestätigen Sie den ursprünglichen fehlgeschlagenen PaymentIntent, indem Sie das Client-Geheimnis wiederverwenden, statt ein neues zu erstellen.

Wenn die Zahlung fehlgeschlagen ist, weil eine Authentifizierung erforderlich war, versuchen Sie es erneut mit der vorhandenen PaymentMethod, statt eine neue zu erstellen.

fun startRecoveryFlow(clientSecret: String) {
    // ...continued from previous step
    val paymentConfiguration = PaymentConfiguration.getInstance(applicationContext)
    val paymentLauncher = PaymentLauncher.Companion.create(
        this,
        paymentConfiguration.publishableKey,
        paymentConfiguration.stripeAccountId,
        ::onPaymentResult
    )

    val lastPaymentError = paymentIntent.lastPaymentError
    val lastPaymentMethodId = lastPaymentError.paymentMethod?.id
    if (lastPaymentError?.code == "authentication_required" && lastPaymentMethodId != null) {
        // Payment failed because authentication is required, reuse the PaymentMethod
        val paymentIntentParams =
            ConfirmPaymentIntentParams.createWithPaymentMethodId(
                lastPaymentMethodId,
                clientSecret // Reuse the existing PaymentIntent
            )
        // Submit the payment...
        paymentLauncher.confirm(paymentIntentParams)
    } else {
        // Collect a new PaymentMethod from the customer...
    }
}

An diesem Punkt sollten Sie über eine Integration verfügen, für die Folgendes gilt:

1. Kartenangaben werden mit einem SetupIntent erfasst und gespeichert, ohne die Karte des/der Kund/in zu belastet.
2. Off-Session-Belastung von Karten wird durchgeführt, und Ablehnungen und Authentifizierungsanfragen werden über einen Wiederherstellungsablauf abgewickelt.

Sie können mehrere Testkarten einsetzen, um sicherzustellen, dass diese Integration bereit für den Einsatz in einer Produktionsumgebung ist. Die Karten können Sie mit beliebigen CVCs, Postleitzahlen und zukünftigem Ablaufdatum verwenden.

Siehe dazu die vollständige Liste der Testkarten.