Kartenzahlungen einziehen
Bereiten Sie Ihre Anwendung und Ihr Backend auf das Einziehen von Kartenzahlungen mit Stripe Terminal vor.
Notiz
Für intelligente Lesegeräte wie das BBPOS WisePOS E oder den Stripe Reader S700 empfehlen wir die servergestützte Integration anstelle des JavaScript SDK. Bei der servergestützten Integration werden Zahlungen mit der Stripe API erfasst, anstatt auf die lokale Netzwerkkommunikation zu vertrauen. Sehen Sie sich unseren Plattformvergleich an und finden heraus, welche Plattform am besten zu Ihrem Unternehmen passt.
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:
- PaymentIntent erstellen.
- Zahlungsmethode erfassen. Sie können definieren, ob Ihre Zahlungen automatisch oder manuell erfasst werden sollen.
- Verarbeiten the payment. Die Autorisierung der Kundenkarte erfolgt, wenn das SDK die Zahlung verarbeitet.
- (Optional) Zahlung erfassen
Notiz
Diese Integrationsform unterstützt keine Offline-Kartenzahlungen.
Erstellen Sie ein PaymentIntentServerseitig
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.
Verwenden Sie Test-Beträge, um verschiedene Ergebnisse zu erzielen. Ein Betrag, der auf 00
endet, führt zu einer bestätigten Zahlung.
Das folgende Beispiel zeigt, wie Sie einen PaymentIntent
auf Ihrem Server erstellen:
Für Terminal-Zahlungen muss der Parameter payment_
card_
enthalten.
Sie können den Zahlungsablauf wie folgt steuern:
- Um den Zahlungsablauf für
card_
-Zahlungen vollständig zu steuern, setzen Siepresent capture_
aufmethod 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_
aufmethod automatic
.
Um Interac-Zahlungen in Kanada anzunehmen, müssen Sie außerdem interac_
in payment_
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.
Verwenden Sie das Client-Geheimnis als Parameter beim Aufruf von collectPaymentMethod.
Sie benötigen in Ihrer clientseitigen Anwendung nur das client_
, um mit der Erfassung der Zahlungsmethode fortzufahren.
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.
async () => { // clientSecret is the client_secret from the PaymentIntent you created in Step 1. const result = await terminal.collectPaymentMethod(clientSecret); if (result.error) { // Placeholder for handling result.error } else { // Placeholder for processing result.paymentIntent } }
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 update_
, um dem serverseitigen PaymentIntent
eine PaymentMethod
zuzuordnen. Diese Daten werden in der collectPaymentMethod
-Antwort zurückgegeben.
async () => { // clientSecret is the client_secret from the PaymentIntent you created in Step 1. const result = await terminal.collectPaymentMethod(clientSecret, { config_override: { update_payment_intent: true } }); if (result.error) { // Placeholder for handling result.error } else { const pm = result.paymentIntent.payment_method const card = pm?.card_present ?? pm?.interac_present // Placeholder for business logic on card before processing result.paymentIntent } }
Notiz
Diese Methode fügt die erfassten verschlüsselten Zahlungsmethodendaten mit einer Aktualisierung an das PaymentIntent
-Objekt an. Bis zum nächsten Schritt ist keine Autorisierung erforderlich: Verarbeiten der Zahlung.
Dieser erweiterte Use case wird auf dem Verifone P400 nicht unterstützt.
Nach Erfassung der Zahlungsmethode müssen Sie die Zahlung autorisieren oder den Einzug innerhalb von 30 Sekunden abbrechen.
Wenn das SDK offline ist, ist das Feld paymentMethod
im PaymentIntent
-Objekt nicht vorhanden.
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.
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.
zuverlässig.
Erfassung abbrechen
Programmgesteuerte Stornierung
Sie können die Erfassung einer Zahlungsmethode durch Aufruf von cancelCollectPaymentMethod im JavaScript SDK stornieren.
Kundenseitig initiierte Stornierung
Wenn Sie enable_
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.collectPaymentMethod( clientSecret, { config_override: { enable_customer_cancellation: true } } )
Ereignisse verarbeiten
Notiz
Das JavaScript SDK unterstützt nur die Lesegeräte Verifone P400, BBPOS WisePOS E und Stripe Reader S700, die über einen integrierten Bildschirm verfügen. Ihre Anwendung muss Nutzer/innen 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 Kassierer/innen die rote X-Taste drücken.
Zahlung bestätigenClientseitig
Nachdem eine Zahlungsmethode erfolgreich vom Kunden/von der Kundin erfasst wurde, müssen Sie als Nächstes die Zahlung mit dem SDK verarbeiten. Wenn Sie bereit sind, mit der Zahlung fortzufahren, rufen Sie processPayment
mit dem aktualisierten PaymentIntent
aus Schritt 2 auf.
- Bei einer manuellen Erfassung von Zahlungen führt ein erfolgreicher Aufruf von
processPayment
zu einemPaymentIntent
mit dem Statusrequires_
.capture - Bei einer automatischen Erfassung von Zahlungen wechselt der
PaymentIntent
zum Statussucceeded
.
Notiz
Bestätigen Sie PaymentIntents immer mithilfe des Terminal SDK auf der Client-Seite. Bei der serverseitigen Bestätigung werden wichtige Interaktionen, wie z. B. PIN-Abfragen, umgangen, was zu fehlgeschlagenen Transaktionen führen kann.
async () => { const result = await terminal.processPayment(paymentIntent); if (result.error) { // Placeholder for handling result.error } else if (result.paymentIntent) { // Placeholder for notifying your backend to capture result.paymentIntent.id } }
Achtung
Sie müssen einen PaymentIntent innerhalb von 2 Tagen manuell erfassen. Andernfalls läuft die Autorisierung ab und die Gelder werden für den Kunden/die Kundin freigegeben.
Umgang mit Fehlern
Wenn das Abwickeln 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_ | Zahlungsmethode abgelehnt | Versuchen Sie, eine andere Zahlungsmethode zu erfassen, indem Sie collectPaymentMethod mit demselben PaymentIntent erneut aufrufen. |
requires_ | Vorübergehendes Verbindungsproblem | Rufen Sie processPayment mit demselben PaymentIntent erneut auf, um die Anfrage zu wiederholen. |
PaymentIntent ist nil | Anfrage an Stripe ist abgelaufen, unbekannter Status des PaymentIntent | Versuchen Sie, den ursprünglichen PaymentIntent erneut zu verarbeiten. Erstellen Sie keinen neuen, 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_
befinden, bevor Stripe ihn {verarbeiten kann. Ein autorisierter, erfasster oder stornierter PaymentIntent
kann nicht von einem Lesegerät verarbeitet werden.
Zahlung erfassenServerseitig
Wenn Sie bei der Erstellung des PaymentIntent
in Schritt 1 capture_
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_
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 storniertenPaymentIntent
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.