Kartenzahlungen offline einziehenBeta
Mit dem Terminal SDK kann Ihre Anwendung weiterhin Zahlungen über ein mobiles Lesegerät ohne Netzwerkverbindung einziehen.
Achtung
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. Sie als Nutzer/in tragen das gesamte Risiko für die Ablehnung der Transaktion. Wenn der/die Aussteller/in die Offline-Transaktion ablehnt, gibt es keine Möglichkeit, die Gelder zurückzufordern, und Sie erhalten möglicherweise keine Zahlung von dem/der Kund/in 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
- Zahlung erfassen
- Offline-Zahlungen prüfen
Offline-Modus aktivieren
Um den Offline-Modus zu verwenden, muss Ihre Anwendung mindestens die Version 3.3.0 des Terminal iOS SDK verwenden.
Verwenden Sie ein Konfigurations-Objekt, um den Offline-Modus für das Lesegerät BBPOS Chipper 2X BT, Stripe Reader M2 oder BBPOS WisePad 3 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 Parameter Location
nach der Online-Verbindung lokal ab. Bei zukünftigen Offline-Verbindungen verwendet das SDK dann die gespeicherten Konfigurationsinformationen von Location
.
Um im Offline-Modus eine Verbindung mit einem Lesegerät herzustellen, müssen Sie innerhalb der letzten 30 Tage online eine Verbindung mit einem Bluetooth-Lesegerät desselben Typs und desselben Location
hergestellt 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 Parameter Location für den Offline-Modus konfiguriert ist. Wenn Location ordnungsgemäß konfiguriert ist, hat Ihr POS im Online-Modus zuvor keine Verbindung zu Lesegeräten hergestellt. Sie sollten sich zuerst mit einem beliebigen Lesegerät verbinden, während Sie online sind, und sich dann mit einem Lesegerät desselben Typs verbinden, 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 eine Aktualisierung vorzunehmen. |
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, verlieren Sie alle Zahlungen, die im SDK gespeichert und noch nicht weitergeleitet wurden. Stellen Sie sicher, dass keine Zahlungen gespeichert sind, bevor Sie destruktive Aktionen durchführen.
Offline-Ereignisse verarbeitenClient-seitig
Implementieren Sie das OfflineDelegate
-Protokoll und übergeben Sie es/sie an Terminal, um Ihre Anwendung über offline-bezogene Ereignisse zu informieren. Sie müssen OfflineDelegate
festlegen, bevor Sie Zahlungen offline erfassen.
Sie können auch Terminal.offlineStatus.sdk.networkStatus
nach dem aktuellen Netzwerkstatus des SDK abfragen.
Das SDK versucht, Zahlungen weiterzuleiten, auch wenn der Netzwerkstatus offline ist. Dies bedeutet, dass der Anbieter Ihres Verbindungs-Token möglicherweise eine Anfrage zur Bereitstellung eines Verbindungs-Tokens erhält, selbst wenn der Netzwerkstatus des SDK offline ist. Während des Zahlungseinzugs legt der Netzwerkstatus fest, ob das SDK die Zahlung online verarbeitet oder sie sofort speichert.
PaymentIntent offline erstellenClient-seitig
Um den Offline-Betrieb zu unterstützen, müssen Sie den Parameter createPaymentIntent
des SDK verwenden, um PaymentIntent-Objekte zu erstellen.
Während des Offline-Betriebs haben PaymentIntent
-Objekte die stripeId
Null. Wir empfehlen Ihnen, den Metadaten des PaymentIntent eine nutzerdefinierte Kennung hinzuzufügen, um offline erstellte PaymentIntent
-Objekte abzugleichen. Innerhalb Ihres OfflineDelegate.didForwardPaymentIntent
können Sie Ihre Kennung verwenden, um Offline-Zahlungen mit Zahlungen zu korrelieren, die erfolgreich an Stripe weitergeleitet wurden.
Risikomanagement bei Offline-Zahlungen
Der Terminal.createPaymentIntent
akzeptiert einen Parameter des Typs CreateConfiguration
. Wenn Sie offline arbeiten, werden standardmäßig alle Offline-Zahlungen gespeichert und an das Backend von Stripe weitergeleitet, sobald die Verbindung wiederhergestellt ist. Sie können ein CreateConfiguration
-Objekt übergeben, dessen offlineBehavior
auf REQUIRE_ONLINE
gesetzt ist, um die aktuelle Transaktion abzuweisen, wenn Sie offline arbeiten. Möglicherweise möchten Sie Transaktionen über einen bestimmten Betrag untersagen oder sämtliche Offline-Transaktionen untersagen, wenn das SDK eine Reihe von Transaktionen gespeichert hat, deren Summe einen bestimmten Betrag überschreitet (siehe Terminal.offlineStatus.sdk.offlinePaymentAmountsByCurrency
).
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
Standardmäßig bestimmt das Terminal SDK anhand Ihrer Netzwerkverbindung automatisch, ob Zahlungen online oder offline eingezogen werden sollen. Es kann jedoch vorkommen, dass Sie trotz aktiver Netzwerkverbindung offline arbeiten möchten – beispielsweise, wenn Sie Transaktionen schnell erfassen müssen und Ihre Netzwerkverbindung langsam ist. Sie können ein CreateConfiguration
-Objekt übergeben, dessen offlineBehavior
auf FORCE_OFFLINE
gesetzt ist, um die Zahlung unabhängig von der Verbindung offline einzuziehen. Beachten Sie, dass Zahlungen, die offline eingezogen werden, während das Terminal-SDK über eine aktive Netzwerkverbindung verfügt, im Hintergrund weitergeleitet werden.
Zahlungsmethode erfassenClient-seitig
Das Durchziehen von Karten wird im Offline-Modus nicht unterstützt. Das Auflegen von Karten wird in Märkten, in denen die starke Kundenauthentifizierung erforderlich ist, ebenfalls nicht unterstützt. Verwenden Sie die Methode BluetoothReaderDelegate didRequestReaderInput , um Kundinnen und Kunden mögliche Optionen für die Vorlage ihrer Karten anzuzeigen. Im Offline-Modus ist der Parameter initWithUpdatePaymentIntent
bei CollectConfiguration
deaktiviert, außer wenn offlineBehavior
auf REQUIRE_ONLINE
eingestellt ist.
Notiz
Die Zahlungspflicht liegt in Ihrer Verantwortung, wenn Sie Ihr Lesegerät offline betreiben. Da magnetische Stripe-Daten leicht zu fälschen sind, lässt Stripe diese Option im Offline-Betrieb nicht zu.
Zahlung bestätigenClient-seitig
Dieser Schritt ähnelt der Online-Bestätigung von Zahlungen. Der Hauptunterschied besteht darin, dass Ihre Integration spezifische Offline-Fehlerfälle handhaben muss, z. B. wenn die Transaktion den von Stripe erzwungenen Offline-Höchstbetrag in Höhe von 10.000 USD oder einem entsprechenden Betrag in Ihrer genutzten Wä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. Über den Parameter offlineDetails.storedAt
finden Sie heraus, ob die Bestätigung offline erfolgt ist.
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 seine OfflineCardPresentDetails aus der Eigenschaft paymentIntent.offlineDetails.offlineCardPresentDetails
ab.
Dieser Hash enthält eine Eigenschaft ReceiptDetails , die Sie zum Generieren eines Belegs verwenden können, sowie weitere Kartendaten wie den Namen des Karteninhabers/der Karteninhaberin und die Kartenmarke.
Während des Offline-Betriebs sind nicht alle Belegdetails verfügbar. Vordefinierte E-Mail-Belege werden nur 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.
Wenn Sie Ihr POS-Gerät zu früh ausschalten, werden Ihre Zahlungen möglicherweise nicht weitergeleitet. Sie können Terminal.offlineStatus.sdk.networkStatus
abfragen, um sicherzustellen, dass Ihr POS online ist und Zahlungen weiterleiten kann, und Terminal.offlineStatus.sdk.offlinePaymentsCount
, um zu überprüfen, wie viele Zahlungen noch weitergeleitet werden müssen.
Zahlung erfassen
Notiz
Während Sie offline sind, können Sie PaymentIntents erstellen, deren captureMethod
auf automatic
gesetzt ist. Nach der Bestätigung haben diese PaymentIntents den Status Succeeded
anstelle von RequiresCapture
. Sie werden automatisch bei der Weiterleitung erfasst.
Zahlungen, die erfolgreich weitergeleitet und autorisiert wurden, müssen von Ihrem Backend oder Ihrer Anwendung erfasst werden:
- Zum Erfassen von Zahlungen von Ihrem Backend verwenden Sie Webhooks, um PaymentIntents mit dem Status
requires_capture
zu erstellen. - Um Zahlungen aus Ihrer Anwendung zu erfassen, warten Sie auf Aufrufe von
OfflineDelegate.didForwardPayment
für jeden PaymentIntent, der weitergeleitet wird. Ein PaymentIntent ist bereit für die Erfassung, wenn sein StatusRequiresCapture
ist.
Wenn Ihre Anwendung bestimmt, wann ein PaymentIntent nach confirmPaymentIntent
erfasst werden soll, ist sie bereit zur Erfassung, wenn der Status RequiresCapture
ist und die offlineDetails
null sind oder wenn sie den Status requiresUpload
mit dem Wert NO
hat.
Erfassen Sie eine Zahlung nach confirmPaymentIntent
, wenn sie online bestätigt wird:
Erfassen Sie eine Offline-Zahlung, nachdem sie in Ihrem OfflineDelegate’s didForwardPaymentIntent
weitergeleitet worden ist:
Offline eingezogene Zahlungen prüfen
Nach der Autorisierung können Sie die PaymentIntents API verwenden, um Details zu 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.