Kartenzahlungen offline einziehen
Ziehen Sie Kartenzahlungen ein, wenn Sie Probleme mit der Internetverbindung haben.
Mit dem Terminal SDK kann Ihre Anwendung weiterhin Zahlungen über ein mobiles Lesegerät ohne Netzwerkverbindung einziehen.
Häufiger Fehler
Beim Offline-Betrieb werden die Zahlungsinformationen zum Zeitpunkt des Verkaufs erfasst, und erst nachdem die Verbindung wiederhergestellt und die Zahlung weitergeleitet wurde, wird versucht, die Autorisierung durchzuführen. Als Nutzer/in übernehmen Sie alle mit einer Offline-Transaktion verbundenen Ablehnungs- und Manipulationsrisiken. Wenn Ihr manipuliertes Lesegerät keine Zahlungen an Stripe weiterleiten kann oder der Kartenaussteller die Transaktion ablehnt, gibt es keine Möglichkeit, die Gelder zurückzuerhalten. Und Sie erhalten möglicherweise keine Zahlung von den Kundinnen und Kunden für bereits bereitgestellte Waren oder Dienstleistungen.
Um die Wahrscheinlichkeit zu verringern, dass Zahlungen von Ausstellern abgelehnt werden, sollten Sie:
- Stellen Sie die Internetverbindung so schnell wie möglich wieder her, um die Zahlungen an Stripe zu erfassen.
- Beschränken Sie Transaktionen, wenn sie einen bestimmten Betrag überschreiten.
- Lassen Sie alle Offline-Zahlungen fehlschlagen, wenn das SDK eine Reihe von Transaktionen gespeichert hat, deren Summe einen bestimmten Betrag übersteigt.
Zahlungen offline einziehen
Offline-Zahlungen umfassen dieselben Schritte wie Online-Zahlungen: Zahlung erstellen, einziehen, verarbeiten und erfassen. Ihr Gerät kann in jedem Schritt des Prozesses von online zu offline wechseln.
- Offline-Modus aktivieren
- Offline mit einem Lesegerät verbinden
- Offline-Events verarbeiten
- Payment Intent offline erstellen
- Zahlungsmethode erfassen
- Zahlung bestätigen
- Warten, bis Zahlungen weitergeleitet werden
- (Optional) Zahlung erfassen
- (Optional) Offline-Zahlungen prüfen
Offline-Modus aktivieren
Um den Offline-Modus zu verwenden, muss Ihre Anwendung Version 3.
oder höher des Terminal iOS SDK nutzen.
Verwenden Sie ein Konfigurations-Objekt oder das Dashboard, um den Offline-Modus für die unterstützten Geräte an Ihrem Location
zu aktivieren.
Nachdem Sie den Offline-Modus für ein Configuration
-Objekt aktiviert haben, können Sie es einem Location
zuweisen. Sie können den Offline-Modus auch standardmäßig für alle Locations
aktivieren, indem Sie das standardmäßige Configuration
-Objekt für Ihr Konto aktualisieren. Es kann mehrere Minuten dauern, bis Änderungen der Configuration API auf Ihr SDK und Lesegerät übertragen werden, und es kann erforderlich sein, dass Sie die Verbindung mit Ihrem Lesegerät trennen und wiederherstellen müssen, damit die Änderungen wirksam werden.
Offline mit einem Lesegerät verbinden
Das SDK speichert die erforderlichen Informationen zum Location
nach der Online-Verbindung lokal. Bei nachfolgenden Offline-Verbindungen werden die gespeicherten Konfigurationsinformationen von diesem Location
verwendet.
Um Zahlungen mit einem intelligenten Lesegerät einzuziehen, während Sie offline sind, müssen Sie zuvor innerhalb der letzten 30 Tage mit einem mobilen Lesegerät desselben Typs, am selben Location
und die Software Ihres Lesegeräts innerhalb dieser Zeit aktualisiert haben.
Wenn Sie im Offline-Modus versuchen, eine Verbindung zu einem Lesegerät herzustellen, und diese Anforderungen nicht erfüllen, schlägt die Anfrage mit einem Fehler fehl.
Fehler | Auflösung |
---|---|
Das SDK ist nicht mit dem Internet verbunden | Stellen Sie sicher, dass der von Ihnen verwendete Location für den Offline-Modus konfiguriert ist. Andernfalls stellen Sie eine Verbindung zu einem beliebigen Lesegerät her, während Sie online sind, und stellen Sie dann eine Verbindung zu einem Lesegerät desselben Typs her, während Sie offline sind. |
Das ausgewählte Lesegerät benötigt ein Software-Update, bevor Offline-Zahlungen eingezogen werden können. | Die Software des Lesegeräts wurde seit mindestens 30 Tagen nicht mehr aktualisiert. Stellen Sie eine Verbindung zum Lesegerät her, wenn Sie online sind, um es zu aktualisieren. |
Das ausgewählte Lesegerät muss an diesem Standort erst online gekoppelt werden, bevor Offline-Zahlungen eingezogen werden können. | Sie versuchen, eine Verbindung mit einem Lesegerätetyp herzustellen, mit dem Ihr POS zuvor noch nicht im Online-Modus verbunden wurde. Sie müssen sich zuerst mit diesem Lesegerät oder einem Lesegerät desselben Typs verbinden, während Sie online sind. Wenn Sie sich offline verbinden möchten, können Sie sich mit einem Lesegerätetyp verbinden, mit dem Ihr POS online zuvor bereits eine Verbindung aufgebaut hat. |
Wenn Sie die Anwendung neu installieren oder einen Vorgang ausführen, der den Festplattenspeicher für das SDK löscht (z. B. das Löschen des Caches Ihrer POS-App in den Einstellungen des POS-Geräts), verlieren Sie alle Zahlungen, die im SDK gespeichert und noch nicht weitergeleitet wurden. Stellen Sie sicher, dass keine Zahlungen gespeichert sind, bevor Sie zerstörerische Aktionen durchführen.
Offline-Ereignisse verarbeitenClient-seitig
Damit Ihre Anwendung Updates zum Netzwerkstatus des SDK und zum Status der weitergeleiteten Zahlungen erhalten kann, implementieren Sie das OfflineDelegate
-Protokoll und übergeben Sie es an das Terminal SDK. Sie müssen OfflineDelegate
festlegen, bevor Sie Zahlungen im Offline-Modus einziehen können.
PaymentIntent offline erstellenClient-seitig
Um den Offline-Betrieb zu unterstützen, verwenden Sie den Parameter createPaymentIntent
des SDK, um PaymentIntent-Objekte zu erstellen. So kann das SDK im Offline-Modus PaymentIntents erstellen und an Stripe weiterleiten, sobald die Verbindung wiederhergestellt ist.
Während des Offline-Betriebs haben PaymentIntent
-Objekte die stripeId
Null. Wir empfehlen, den Metadaten des PaymentIntent eine nutzerdefinierte Kennung hinzuzufügen, um PaymentIntent
-Objekte abzugleichen, die offline in Ihrer Datenbank erstellt wurden.
Nachdem der PaymentIntent
in Schritt 7 erfolgreich an Stripe weitergeleitet wurde, verwenden Sie Ihre individuelle Kennung, um sie im Aufruf OfflineDelegate.
abzugleichen.
Der Parameter Terminal.
akzeptiert den Parameter CreateConfiguration
. Wenn Sie offline arbeiten, speichert das Terminal SDK standardmäßig alle Offline-Zahlungen und leitet sie dann an das Backend von Stripe weiter, sobald die Verbindung wiederhergestellt ist.
Um dieses Verhalten anzupassen, können Sie ein CreateConfiguration
-Objekt übergeben, wobei das Attribut offlineBehavior
als REQUIRE_
, PREFER_
oder FORCE_
festgelegt ist.
Risikomanagement
Das Festlegen von offlineBehavior
auf REQUIRE_
führt dazu, dass die aktuelle Transaktion fehlschlägt, wenn Sie offline arbeiten. Möglicherweise möchten Sie z. B. Transaktionen über einem bestimmten Betrag oder sämtliche Offline-Transaktionen untersagen, wenn das SDK eine Reihe von Transaktionen gespeichert hat, deren Summe einen bestimmten Betrag überschreitet.
Das SDK bietet zwei Eigenschaften, die Ihnen bei der Risikoverwaltung helfen:
Terminal.
offlineStatus. sdk. offlinePaymentsCount Terminal.
offlineStatus. sdk. offlinePaymentAmountsByCurrency
Verwaltung der Latenz im Offline-Betrieb
Basierend auf Ihrer Netzwerkverbindung bestimmt das Terminal SDK automatisch, ob Zahlungen online oder offline eingezogen werden sollen. Es kann jedoch vorkommen, dass Sie trotz aktiver Netzwerkverbindung offline arbeiten möchten (z. B. wenn Sie Transaktionen schnell erfassen müssen und Ihre Netzwerkverbindung langsam ist). Sie können ein CreateConfiguration
-Objekt übergeben, dessen offlineBehavior
auf FORCE_
gesetzt ist, um die Zahlung unabhängig von der Verbindung offline einzuziehen.
Zahlungen, die offline eingezogen werden, während das SDK von Terminal über eine aktive Netzwerkverbindung verfügt, werden im Hintergrund weitergeleitet.
Zahlungsmethode erfassenClient-seitig
Notiz
Die Zahlungspflicht liegt in Ihrer Verantwortung, wenn Sie Ihr Lesegerät offline betreiben. Da Magnetstreifendaten leicht zu fälschen sind, lässt Stripe diese Option im Offline-Betrieb nicht zu. Das Antippen von Karten wird auch nicht in Märkten unterstützt, in denen eine starke Kundenauthentifizierung erforderlich ist.
Der Einzug von Zahlungen im Offline-Modus ähnelt dem Einziehen von Zahlungen online. Verwenden Sie die Methode didRequestReaderInput
, um Kundinnen/Kunden die gültigen Optionen zur Vorlage der Karte anzuzeigen.
Notiz
Die Überprüfung der Angaben zur Zahlungsmethode vor der Autorisierung wird im Offline-Modus nicht unterstützt. Sie können zwar weiterhin den Parameter initWithUpdatePaymentIntent
in CollectConfiguration
verwenden, das Feld paymentMethod
für den PaymentIntent fehlt jedoch, wenn das SDK offline arbeitet.
Zahlung bestätigenClient-seitig
Das Bestätigen von Zahlungen im Offline-Modus ähnelt dem Bestätigen von Zahlungen online. Der Hauptunterschied besteht darin, dass Ihre Integration offline-spezifische Fehlerfälle handhaben muss, z. B. wenn die Transaktion den von Stripe erzwungenen Offline-Höchstbetrag von 10.000 USD oder den Gegenwert in Ihrer Betriebswährung überschreitet.
In einigen Fällen erstellt das SDK möglicherweise online einen PaymentIntent
, bestätigt diesen jedoch offline. Wenn dies geschieht, hat der PaymentIntent
möglicherweise eine stripeId
, die nicht Null ist. Wenn er offline bestätigt wurde, wird offlineDetails
definiert und ausgefüllt.
Ausstellung von Belegen
Möglicherweise benötigen Sie Informationen über die Karte, mit der Sie eine Zahlung offline abschließen können. Beispielsweise müssen Sie möglicherweise einen Beleg für Kundinnen/Kunden erstellen, die diesen zum Zeitpunkt des Kaufs benötigen.
Wenn der PaymentIntent offline bestätigt wird, rufen Sie ihre OfflineCardPresentDetails from the paymentIntent.
-Eigenschaft ab.
Dieser Hash enthält eine ReceiptDetails -Eigenschaft, die Sie zum Generieren eines Belegs verwenden können, sowie weitere Kartendaten wie die Name und Marke der Karteninhaberin/des Karteninhabers.
Die Belegfelder account_
und authorization_
sind bei offline verarbeiteten PaymentIntents nicht verfügbar. Vordefinierte E-Mail-Belege werden erst gesendet, nachdem die Verbindung wiederhergestellt und die Zahlung erfolgreich erfasst wurde.
Warten Sie, bis die Zahlungen weitergeleitet wurdenClient-seitig
Wenn die Internet access wiederhergestellt wird, beginnt das SDK automatisch mit der Weiterleitung der gespeicherten Offline-Zahlungen.
Das SDK versucht, Zahlungen weiterzuleiten, auch wenn sein Netzwerkstatus offline ist. Dies bedeutet, dass der Anbieter Ihres Verbindungs-Tokens möglicherweise eine Anfrage zur Bereitstellung eines Verbindungs-Tokens erhält, auch wenn das Gerät offline ist.
Wenn Sie Ihr POS-Gerät zu früh ausschalten, werden Ihre Zahlungen möglicherweise nicht weitergeleitet. Sie können Terminal.
abfragen, um sicherzustellen, dass Ihr POS online ist und Zahlungen weiterleiten kann und Terminal.
, um zu überprüfen, wie viele Zahlungen an das Terminal-SDK weitergeleitet werden müssen.
Zahlung erfassen
Während Sie offline sind, können Sie PaymentIntents erstelle, deren captureMethod
auf automatic
gesetzt ist.
Nachdem Sie diese PaymentIntents bestätigt haben, haben sie den Status Succeeded
anstelle von RequiresCapture
. Stripe erfasst die Zahlungen automatisch, nachdem Sie sie weitergeleitet haben.
Wenn Sie sich für die manuelle Erfassung entscheiden, müssen Zahlungen, die erfolgreich weitergeleitet und autorisiert wurden, von Ihrem Backend oder Ihrer Anwendung erfasst werden.
- Zum Erfassen von Zahlungen von Ihrem Backend verwenden Sie Webhooks, um PaymentIntents mit dem Status
requires_
zu erstellen.capture - Um Zahlungen aus Ihrer Anwendung zu erfassen, warten Sie darauf, dass Ihre Anwendung Aufrufe an
OfflineDelegate.
für jeden PaymentIntent erhält, während das SDK diesen weiterleitet. Ein PaymentIntent ist bereit für die Erfassung, wenn sein StatusdidForwardPayment RequiresCapture
ist undofflineDetails
null ist oder der Wert fürrequiresUpload
gleichNO
ist.
Erfassen Sie eine Offline-Zahlung, nachdem das SDK dieses im didForwardPaymentIntent
Ihres OfflineDelegate weitergeleitet hat:
Offline eingezogene Zahlungen prüfen
Nach der Autorisierung können Sie die PaymentIntents API verwenden, um Details einer Zahlung offline zu untersuchen. Greifen Sie auf die Angaben zur Zahlungsmethode für das neueste Charge-Objekt für einen PaymentIntent
zu, um zu ermitteln, ob die Zahlung offline eingezogen wurde.