Kartenzahlungen einziehen

Der erste Schritt beim Einziehen von Zahlungen ist das Starten des Zahlungsablaufs. Wenn Kundinnen/Kunden den Bestellvorgang abschließen, muss Ihre Anwendung ein PaymentIntent-Objekt erstellen. Dies stellt eine neue Zahlungssitzung auf Stripe dar.

Einen PaymentIntent können Sie auf dem Client oder auf dem Server erstellen.

Verwenden Sie Test-Beträge, um verschiedene Ergebnisse zu erzielen. Ein Betrag, der auf 00 endet, führt zu einer bestätigten Zahlung.

Clientseitig

Erstellen Sie einen PaymentIntent auf Ihrem Client:

val params = PaymentIntentParameters.Builder()
    .setAmount(1000)
    .setCurrency("usd")
    .build()
Terminal.getInstance().createPaymentIntent(
    params,
    object : PaymentIntentCallback {
        override fun onSuccess(paymentIntent: PaymentIntent) {
            // Placeholder for handling successful operation
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)

Serverseitig

Wenn die zum Starten einer Zahlung erforderlichen Informationen in Ihrer App nicht jederzeit verfügbar sind, können Sie den PaymentIntent auch auf Ihrem Server erstellen.

Das folgende Beispiel zeigt, wie Sie einen PaymentIntent auf Ihrem Server erstellen:

curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "amount"=1000 \
  -d "currency"="usd" \
  -d "payment_method_types[]"="card_present" \
  -d "capture_method"="manual"

Für Terminal-Zahlungen muss der Parameter payment_method_types card_present enthalten.

Sie können den Zahlungsablauf wie folgt steuern:

• Um den Zahlungsablauf für card_present-Zahlungen vollständig zu steuern, setzen Sie capture_method auf manual. So können Sie vor der endgültigen Finalisierung der Zahlung einen Abgleichschritt hinzufügen.
• Um Zahlungen in einem Schritt zu autorisieren und zu erfassen, setzen Sie capture_method auf automatic.

Um Zahlungen in Australien anzunehmen, müssen Sie capture_method auf automatic oder manual_preferred setzen. Weitere Details finden Sie in unserer Dokumentation für Australien. Um Interac-Zahlungen in Kanada anzunehmen, müssen Sie außerdem interac_present in payment_method_types angeben. Weitere Details finden Sie in unserer Dokumentation für Kanada.

Der PaymentIntent enthält ein Client-Geheimnis, einen Schlüssel, der für jeden PaymentIntent eindeutig ist. Um das Client-Geheimnis zu verwenden, müssen Sie es vom PaymentIntent auf Ihrem Server beziehen und an den Client übergeben.

post '/create_payment_intent' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end

Um einen PaymentIntent abzurufen, rufen Sie mithilfe des Client-Geheimnisses retrievePaymentIntent auf.

Nachdem Sie den PaymentIntent abgerufen haben, rufen Sie damit collectPaymentMethod auf.

Terminal.getInstance().retrievePaymentIntent(
    clientSecret,
    object : PaymentIntentCallback {
        override fun onSuccess(paymentIntent: PaymentIntent) {
            // Placeholder for handling successful operation
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)

Nachdem Sie einen PaymentIntent erstellt haben, erfassen Sie als Nächstes eine Zahlungsmethode mit dem SDK.

Zum Erfassen einer Zahlungsmethode muss Ihre App mit einem Lesegerät verbunden sein. Nach dem Aufruf von collectPaymentMethod durch Ihre App wartet das verbundene Lesegerät darauf, dass eine Karte vorgezeigt wird.

val cancelable = Terminal.getInstance().collectPaymentMethod(
    paymentIntent,
    object : PaymentIntentCallback {
        override fun onSuccess(paymentIntent: PaymentIntent) {
            // Placeholder for handling successful operation
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)

Diese Methode erfasst die verschlüsselten Daten einer Zahlungsmethode mithilfe des verbundenen Lesegeräts und ordnet die verschlüsselten Daten dem lokalen PaymentIntent zu.

Optionale Prüfung der Angaben zur Zahlungsmethode

Für erweiterte Use cases können Sie die Details der Zahlungsmethode der vorgelegten Karte prüfen und Ihre eigene Geschäftslogik vor der Autorisierung ausführen.

Verwenden Sie den Parameter updatePaymentIntent in CollectConfiguration, um dem serverseitigen PaymentIntent eine PaymentMethod zuzuordnen. Diese Daten werden in der collectPaymentMethod-Antwort zurückgegeben.

val collectConfig = CollectConfiguration.Builder()
    .updatePaymentIntent(true)
    .build()

val cancelable = Terminal.getInstance().collectPaymentMethod(paymentIntent,
    object : PaymentIntentCallback {
        override fun onSuccess(paymentIntent: PaymentIntent) {
            val pm = paymentIntent.paymentMethod
            val card = pm?.cardPresentDetails ?: pm?.interacPresentDetails

            // Placeholder for business logic on card before confirming paymentIntent
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)

Sie können an dieser Stelle auf Attribute wie Kartenmarke, Finanzierung und andere nützliche Daten zugreifen.

Erfassung abbrechen

Programmgesteuerte Stornierung

Sie können die Erfassung einer Zahlungsmethode, mit dem vom Android SDK zurückgegebenen Objekt Cancelable abbrechen.

Kundenseitig initiierte Stornierung

Wenn Sie setEnableCustomerCancellation für eine Transaktion auf „true“ gesetzt haben, wird Nutzerinnen und Nutzern von intelligenten Lesegeräten eine Schaltfläche zum Abbrechen angezeigt.

Durch Tippen auf die Schaltfläche „Abbrechen“ wird die aktive Transaktion abgebrochen.

Terminal.getInstance().collectPaymentMethod(
    paymentIntent,
    object : PaymentIntentCallback {
        override fun onSuccess(paymentIntent: PaymentIntent) {
            // Placeholder for handling successful operation
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    },
    CollectConfiguration.Builder()
        .setEnableCustomerCancellation(true)
        .build(),
)

Ereignisse verarbeiten

Beim Erfassen einer Zahlungsmethode mit einem Lesegerät ohne integrierten Bildschirm wie dem Stripe M2 muss Ihre App in der Lage sein, Nutzerinnen und Nutzern Ereignisse zur Erfassung der Zahlungsmethode anzuzeigen. Diese Ereignisse helfen Nutzern/Nutzerinnen beim erfolgreichen Einzug von Zahlungen (z. B. beim erneuten Versuch, eine Karte einzusetzen, beim Ausprobieren einer anderen Karte oder bei Verwendung einer anderen Lesemethode).

Wenn eine Transaktion startet, übergibt das SDK einen ReaderInputOptions-Wert an den Bildschirm-Handler des Lesegeräts Ihrer App, wobei die akzeptierten Eingabetypen (beispielsweise Karte durchziehen, einstecken, kontaktlos nutzen) angezeigt werden. Fordern Sie die Nutzer/innen über die Nutzeroberfläche des Bezahlvorgangs Ihrer App auf, die Karte unter Verwendung einer dieser Optionen vorzulegen.

Während der Transaktion kann das SDK unter Umständen Ihre App auffordern, Ihren Nutzerinnen und Nutzern zusätzliche Anweisungen (beispielsweise „Karte erneut einstecken“) anzuzeigen. Dazu wird ein ReaderDisplayMessage-Wert an den Bildschirm-Handler des Lesegeräts Ihrer App übergeben. Stellen Sie sicher, dass die Nutzeroberfläche Ihres Bezahlvorgangs Ihren Nutzerinnen und Nutzern diese Meldungen anzeigt.

class ReaderActivity : AppCompatActivity(), MobileReaderListener {
    // ...

    override fun onRequestReaderInput(options: ReaderInputOptions) {
        Toast.makeText(activity, options.toString(), Toast.LENGTH_SHORT).show()
    }

    override fun onRequestReaderDisplayMessage(message: ReaderDisplayMessage) {
        Toast.makeText(activity, message.toString(), Toast.LENGTH_SHORT).show()
    }

    // ...
}

Ziehen Sie Zahlungen mit Tap to Pay auf Android ein

Wenn Ihre Anwendung bereit ist, eine Zahlung einzuziehen, übernimmt das Stripe Android SDK die Anzeige, um den Einzugsvorgang abzuwickeln. Nach dem Aufruf von Zahlungsmethode erfassen wird Ihre Anwendung weiterhin ausgeführt. Das Android-Gerät zeigt den Karteninhaberinnen und Karteninhabern eine Aufforderung im Vollbildmodus an, ihre Karte oder NFC-basierte mobile Wallet vorzulegen. Wenn ein Fehler beim Lesen der Karte auftritt, wird eine Aufforderung zum erneuten Versuch angezeigt. Nach erfolgreichem Einlesen der Karte wird eine Erfolgsmeldung angezeigt und Ihre Anwendung kann anschließend die Zahlung bestätigen.

Zahlungseinzug

Nachdem eine Zahlungsmethode erfolgreich vom Kunden/von der Kundin erfasst wurde, müssen Sie als Nächstes die Zahlung mit dem SDK bestätigen. Wenn Sie bereit sind, mit der Zahlung fortzufahren, rufen Sie confirmPaymentIntent mit dem aktualisierten PaymentIntent aus Schritt 2 auf.

• Bei einer manuellen Erfassung von Zahlungen führt ein erfolgreicher Aufruf von confirmPaymentIntent zu einem PaymentIntent mit dem Status requires_capture.
• Bei einer automatischen Erfassung von Zahlungen wechselt der PaymentIntent zum Status succeeded.

val cancelable = Terminal.getInstance().confirmPaymentIntent(
    paymentIntent,
    object : PaymentIntentCallback {
        override fun onSuccess(paymentIntent: PaymentIntent) {
            // Placeholder handling successful operation
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)

Umgang mit Fehlern

Wenn das Bestätigen einer Zahlung fehlschlägt, gibt das SDK einen Fehler zurück, der den aktualisierten PaymentIntent beinhaltet. Ihre Anwendung muss den PaymentIntent prüfen, um zu entscheiden, wie der Fehler gehandhabt wird.

Wenn Anfragen mehrmals hintereinander ablaufen, liegt möglicherweise ein Verbindungsproblem vor. Stellen Sie sicher, dass Ihre App mit dem Internet verbunden ist.

Doppelte Abbuchungen vermeiden

Das PaymentIntent-Objekt ermöglicht Geldbewegungen bei Stripe – verwenden Sie einen einzigen PaymentIntent, um eine Transaktion darzustellen.

Verwenden Sie denselben PaymentIntent, nachdem eine Karte abgelehnt wurde (z. B. wenn sie nicht ausreichend gedeckt ist), damit Ihre Kundin/Ihr Kunde es mit einer anderen Karte erneut versuchen kann.

Wenn Sie den PaymentIntent bearbeiten, müssen Sie collectPaymentMethod aufrufen, um die Zahlungsinformationen auf dem Lesegerät zu aktualisieren.

Ein PaymentIntent muss sich im Status requires_payment_method befinden, bevor Stripe ihn {bestätigen kann. Ein autorisierter, erfasster oder stornierter PaymentIntent kann nicht von einem Lesegerät bestätigt werden.

Wenn Sie bei der Erstellung des PaymentIntent in Schritt 1 capture_method als manual definiert haben, gibt das SDK einen autorisierten, aber nicht erfassten PaymentIntent an Ihre Anwendung zurück. Erfahren Sie mehr über den Unterschied zwischen Autorisierung und Erfassung.

Wenn Ihre App einen bestätigten PaymentIntent von Ihrem SDK empfängt, stellen Sie sicher, dass Ihr Backend angewiesen wird, die Zahlung zu erfassen. Erstellen Sie einen Endpoint in Ihrem Backend, der eine PaymentIntent-ID akzeptiert und eine Anfrage zum Erfassen des PaymentIntent an die Stripe-API übermittelt:

curl -X POST https://api.stripe.com/v1/payment_intents/{{PAYMENT_INTENT_ID}}/capture \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Eine erfolgreiche capture führt zu einem PaymentIntent mit dem Status succeeded.

Zahlungen abgleichen

Um die Zahlungsaktivität Ihres Unternehmens zu überwachen, können Sie am Tagesende PaymentIntents mit Ihrem internen Bestellsystem auf Ihrem Server abgleichen.

Ein PaymentIntent, der den Status requires_capture beibehält, kann eines der folgenden zwei Szenarien darstellen:

Überflüssige Autorisierung auf der Kartenabrechnung Ihrer Kundin/Ihres Kunden

• Ursache: Der/die Nutzer/in hat den Bezahlvorgang Ihrer App während einer Transaktion verlassen.
• Lösung: Wenn der nicht erfasste PaymentIntent keiner abgeschlossenen Bestellung auf Ihrem Server zugeordnet ist, können Sie ihn abbrechen. Sie können einen stornierten PaymentIntent nicht zur Durchführung von Zahlungen verwenden.

Unvollständiger Einzug von Geldern von einer Kundin/einem Kunden

• Ursache: Die Anfrage Ihrer App, die Ihr Backend zur Erfassung der Zahlung anweist, ist fehlgeschlagen.
• Lösung: Wenn der nicht erfasste PaymentIntent einer abgeschlossenen Bestellung auf Ihrem Server zugeordnet ist und keine andere Zahlung (zum Beispiel eine Barzahlung) für die Bestellung angenommen wurde, können Sie ihn erfassen.

Trinkgelder einziehen US only

In den USA können anspruchsberechtigte Nutzer/innen beim Erfassen von Zahlungen Trinkgelder einziehen.