Kartenzahlungen einziehen
Zum Einziehen von Zahlungen mit Stripe Terminal müssen Sie einen Zahlungsablauf in Ihrer Anwendung programmieren. Verwenden Sie das Stripe Terminal SDK, um einen PaymentIntent zu erstellen und zu aktualisieren. Bei einem PaymentIntent handelt es sich um ein Objekt, das eine einzelne Zahlungssitzung darstellt.
Die fehlerresistente Terminal-Integration teilt den Zahlungsvorgang in mehrere Schritte auf, von denen jeder sicher erneut versucht werden kann:
In Schritt 1 können Sie definieren, ob Ihre Zahlungen automatisch oder manuell erfasst werden sollen. Die Autorisierung auf der Karte des/der Kund/in findet in Schritt 3 statt, wenn das SDK die Zahlung confirms.
PaymentIntent erstellenClientseitigServerseitig
Der erste Schritt beim Einziehen von Zahlungen ist das Starten des Zahlungsablaufs. Wenn Kund/innen den Bestellvorgang abschließen, muss Ihre Anwendung ein PaymentIntent
-Objekt erstellen. Dieses Objekt stellt eine neue Zahlungssitzung bei 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:
Achtung
Wenn Ihre App mit dem Lesegerät Verifone P400 verbunden ist, können Sie keinen PaymentIntent über das iOS SDK erstellen. Sie müssen stattdessen den PaymentIntent auf dem Server erstellen und den PaymentIntent in Ihrer App mithilfe der SDK-Methode Terminal.retrievePaymentIntent
abrufen.
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:
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 diecapture_method
aufmanual
. Dadurch 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
aufautomatic
.
Notiz
In Australien müssen Sie capture_method
auf automatic
oder manual_preferred
festlegen. Weitere Details finden Sie in unserer Dokumentation für Australien.
Notiz
Um Interac-Zahlungen in Kanada anzunehmen, müssen Sie außerdem interac_present
zu Ihren payment_method_types
hinzufügen. 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 einmalig ist. Um das Client-Geheimnis zu verwenden, müssen Sie es vom PaymentIntent auf Ihrem Server abrufen und an den Client übergeben.
Rufen Sie zunächst unter Verwendung des Client-Geheimnisses retrievePaymentIntent
auf und rufen Sie dann unter Verwendung des abgerufenen PaymentIntent collectPaymentMethod
auf.
Zahlungsmethode erfassenClientseitig
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.
Diese Methode erfasst die verschlüsselten Daten einer Zahlungsmethode mithilfe des verbundenen Lesegeräts und ordnet die verschlüsselten Daten dem lokalen PaymentIntent zu.
Vorsicht
Die Erfassung einer Zahlungsmethode erfolgt lokal und erfordert keine Autorisierung oder Aktualisierung des Payment Intents API-Objekts bis zum nächsten Schritt: confirm der Zahlung.
Optional die Angaben zur Zahlungsmethode prüfen Beta
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 initWithUpdatePaymentIntent
in CollectConfiguration
, um eine PaymentMethod mit dem serverseitigen PaymentIntent zu verknüpfen. Diese Daten werden in der collectPaymentMethod
-Antwort zurückgegeben.
Notiz
Diese Methode fügt die erfassten verschlüsselten Zahlungsmethoden mit einer Aktualisierung an das PaymentIntent-Objekt an. Sie erfordert keine Autorisierung bis zum nächsten Schritt: Bestätigen der Zahlung.
Dieser erweiterte Use case wird weder auf dem Verifone P400 noch auf simulierten Terminal-Lesegeräten unterstützt.
Sie können an dieser Stelle auf Attribute wie Kartenmarke, Finanzierung und andere nützliche Daten zugreifen.
Notiz
Stripe versucht zu erkennen, ob eine mobile Wallet bei einer Transaktion verwendet wird, wie im Attribut wallet.type
gezeigt. Das Attribut wird jedoch nicht ausgefüllt, wenn die ausstellende Bank die lesegerätegestützte Identifizierung einer mobilen Wallet nicht unterstützt, sodass eine genaue Erkennung nicht garantiert werden kann. Nach der Autorisierung im Bestätigungsschritt erhält Stripe aktuelle Informationen von den Netzwerken und aktualisiert wallet.type
zuverlässig.
Erfassung abbrechen
Programmgesteuerte Stornierung
Sie können die Erfassung einer Zahlungsmethode, mit dem vom iOS 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.
Ereignisse verarbeiten
Beim Erfassen einer Zahlungsmethode mit einem Lesegerät ohne integrierten Bildschirm wie dem BBPOS Chipper 2X BT muss Ihre App in der Lage sein, Nutzerinnen und Nutzern Ereignisse zur Erfassung der Zahlungsmethode anzuzeigen. Dank dieser Ereignisse können Nutzer/innen Zahlungen erfolgreich erfassen (so können Sie beispielsweise Kartenzahlungen erneut versuchen, Zahlungen mit einer anderen Karte versuchen oder eine andere Methode zum Einlesen der Karte verwenden).
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.
Notiz
Ihre Anwendung muss Nutzerinnen und Nutzern keine Ereignisse aus der Erfassung der Zahlungsmethoden anzeigen, da das Lesegerät diese bereits anzeigt. Um die Zahlungsmethode für eine Transaktion zu löschen, können Sie die Anfrage stornieren.
Ziehen Sie Zahlungen mit Tap to Pay auf dem iPhone ein
Wenn Ihre Anwendung bereit ist, eine Zahlung einzuziehen, übernimmt das Stripe iOS SDK die Anzeige, um den Einzugsvorgang abzuwickeln. Nach dem Aufruf von Zahlungsmethode erfassen wird Ihre Anwendung weiterhin ausgeführt. Das iPhone zeigt den Karteninhaberinnen und Karteninhabern dann 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
Zahlung bestätigenClientseitig
Nachdem Sie eine Zahlungsmethode erfolgreich vom Kunden/von der Kundin erfasst haben, 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 einemPaymentIntent
mit dem Statusrequires_capture
. - Bei einer automatischen Erfassung von Zahlungen wechselt der
PaymentIntent
zum Statussucceeded
.
Achtung
Sie müssen PaymentIntents
innerhalb von zwei Tagen manuell erfassen. Andernfalls läuft die Autorisierung ab und die Gelder werden für den/die Kund/in freigegeben.
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.
PaymentIntent-Status | Bedeutung | Lösung |
---|---|---|
requires_payment_method | Zahlungsmethode abgelehnt | Versuchen Sie, eine andere Zahlungsmethode zu erfassen, indem Sie collectPaymentMethod mit demselben PaymentIntent erneut aufrufen. |
requires_confirmation | Vorübergehendes Verbindungsproblem | Rufen Sie confirmPaymentIntent mit demselben PaymentIntent erneut auf, um die Anfrage zu wiederholen. |
PaymentIntent ist nil | Anfrage bei Stripe ist abgelaufen, unbekannter PaymentIntent-Status | Versuchen Sie die Bestätigung des ursprünglichen PaymentIntent erneut. Erstellen Sie keinen neuen PaymentIntent, da dies zu mehreren Autorisierungen für den/die Karteninhaber/in führen könnte. |
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.
Zahlung erfassenServerseitig
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:
Eine erfolgreiche capture
führt zu einem PaymentIntent
mit dem Status succeeded
.
Notiz
Um sicherzustellen, dass die erfasste Plattformgebühr für verbundene Konten korrekt ist, überprüfen Sie jeden PaymentIntent
und ändern Sie die Plattformgebühr bei Bedarf, bevor Sie die Zahlung manuell erfassen.
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. Mit einem abgebrochenen PaymentIntent können keine Abbuchungen mehr ausgeführt werden.
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 den PaymentIntent erfassen.
Trinkgelder einziehen US only
In den USA können anspruchsberechtigte Nutzer/innen beim Erfassen von Zahlungen Trinkgelder einziehen.