Eingaben erfassenBeta
Verfügbar in: 🌎 für Stripe S700 und BBPOS WisePOS E mithilfe einer servergesteuerten Integration, Javascript SDK, iOS SDK oder Android SDK.
Notiz
Um Zugriff auf die Beta-Version von „Eingaben erfassen“ für servergesteuerte Integrationen, Javascript SDK, iOS SDK oder Android SDK anzufordern, senden Sie uns eine E-Mail an stripe-terminal-betas@stripe.com.
Eingaben erfassen
Mit den intelligenten Lesegeräten von Terminal können Sie nicht nur Zahlungen erfassen, sondern auch Formulare anzeigen und Informationen von Kundinnen/Kunden sammeln. Sie stellen Anfragen an die Stripe API und die API kommuniziert mit dem Lesegerät, um eine vorgefertigte Nutzeroberfläche anzuzeigen, auf der Kundeneingaben erfasst werden. Stripe benachrichtigt Ihr Backend über die Antworten des Kunden/der Kundin mithilfe von Webhooks.
Um Eingaben mit den intelligenten Lesegeräten von Terminal zu erfassen, verwenden Sie den Befehl collect_inputs. Sie können bis zu 5 Eingaben gleichzeitig angeben, die vom Lesegerät der Reihe nach erfasst werden. Die intelligenten Lesegeräte von Stripe unterstützen derzeit 6 Eingabetypen:
- Mit dem Eingabetyp
selection
können Sie bis zu vier Auswahlmöglichkeiten anzeigen. - Der Eingabetyp
signature
ermöglicht die Erfassung einer Unterschrift über den Touchscreen des Lesegeräts. - Mit dem Eingabetyp
email
können Sie eine E-Mail-Adresse von einer Kundin/einem Kunden erfassen. - Mit dem Eingabetyp
phone
können Sie eine Telefonnummer von einem Kunden/einer Kundin erfassen. - Mit dem Eingabetyp
text
können Sie zusätzliche Informationen von Kundinnen/Kunden erfassen. - Mit dem Eingabetyp
numeric
können Sie zusätzliche Informationen von Kundinnen/Kunden erfassen.
Unterstützte Eingabetypen.
Sie können das Erscheinungsbild und das Verhalten aller Eingabetypen anpassen:
- Legen Sie wichtige Eingaben nach Bedarf fest, um sicherzustellen, dass sie erfasst werden. Für erforderliche Eingaben ist die Schaltfläche zum Überspringen ausgeblendet.
- Stellen Sie Ihren Kundinnen/Kunden Kontext zur Verfügung, indem Sie mit custom_text den Text angeben, der für jede Eingabe auf dem Lesegerät angezeigt werden soll.
- Fügen Sie bis zu 4 Umschalter hinzu, die Kundinnen/Kunden für boolesche Optionen, Vereinbarungen oder Anmeldungen (Opt-Ins) aktivieren oder deaktivieren können.
Feldname | Field location | Maximum characters |
title | 40 | |
description | 280 | |
when used with the selection form | ||
description | 100 | |
when used with any other form type | ||
submit_button | 30 | |
skip_button | 14 | |
title | 50 | |
description | 50 | |
E-Mail und Auswahlformular mit Umschalter
Es sind zusätzliche Anpassungen für Auswahl-Eingaben verfügbar. Beim Festlegen der Auswahlmöglichkeiten, die Sie den Kundinnen/Kunden angezeigen möchten, können Sie die Auswahl mithilfe des Design-Parameters hervorheben oder abschwächen.
Primäre und sekundäre Auswahlstile für Designs
Zusätzlich zur Liste der Eingaben können Sie Metadaten in Ihre Anfrage aufnehmen. Die Anfragenutzlast enthält die angegebenen Metadaten, die sowohl in der synchronen Antwort als auch in den Erfolgs- oder Fehler-Webhooks angezeigt werden. Durch Hinzufügen einer eindeutigen Kennung wie beispielsweise einer Kunden-ID oder einer Bestell-ID können Sie den eingehenden Webhook leichter identifizieren und verarbeiten.
Beta
Sie müssen den Header terminal_collect_inputs_beta=v1
einbeziehen, um die Vorschaufunktion collect_inputs
zu verwenden. Das Lesegerät-Objekt enthält das collect_inputs-Objekt nicht in den API-Antworten, wenn Sie den Header weglassen.
Notiz
Verwenden Sie collect_inputs
nicht zum Erfassen vertraulicher Daten (einschließlich geschützter Gesundheitsinformationen und Informationen zu Kundenzahlungskarten) oder anderer gesetzlich eingeschränkter Informationen.
Interaktion mit Kundinnen/Kunden
Wenn das Lesegerät mit der Erfassung von Eingaben beginnt, zeigt es dem Kunden/der Kundin die erste Eingabe aus der von Ihnen angegebenen Liste an. Der Kunde/die Kundin muss eine Auswahl treffen oder eine Unterschrift leisten, um mit den erforderlichen Eingaben fortzufahren. Bei optionalen Eingaben hat der Kunde/die Kundin jedoch die Möglichkeit, zur nächsten angeforderten Eingabe überzugehen.
Nachdem der Kunde/die Kundin alle Eingaben entweder übermittelt oder übersprungen hat, aktualisiert Stripe das Lesegerät-Objekt und sendet den Webhook terminal.reader.action_succeeded
.
Notiz
Sie verpflichten sich in vollem Umfang, sich mit allen geltenden Gesetzen und Vorschriften in Bezug auf Ihre Nutzung dieser Funktion vertraut zu machen und diese einzuhalten, und müssen in Bezug auf diese Nutzung alle erforderlichen Zustimmungen, Autorisierungen, Lizenzen, Rechte und Genehmigungen einholen. Wenn Sie die von einem Terminal-Lesegerät erfassten oder angezeigten Daten verwenden, um Verträge mit Ihren Kundinnen/Kunden abzuschließen oder ihnen Nachrichten zu senden, sind Sie in vollem Umfang für die Rechtsgültigkeit und Durchsetzbarkeit solcher Verträge oder Nachrichten verantwortlich.
Eingabedaten empfangen
Verwenden Sie den folgenden curl-Befehl als Beispiel, um einen Webhook-Endpunkt zu erstellen, um die gesammelten Eingaben zu empfangen.
curl https://api.stripe.com/v1/webhook_endpoints \ -u
: \ --header "Stripe-Version: 2023-10-16; terminal_collect_inputs_beta=v1" \ --data-urlencode "url"="https://example.com/webhook/endpoint" \ --data-urlencode "api_version"="2023-10-16;terminal_collect_inputs_beta=v1" \ --data-urlencode "enabled_events[]"="terminal.reader.action_succeeded" \ --data-urlencode "enabled_events[]"="terminal.reader.action_failed"sk_test_4eC39HqLyjWDarjtT1zdp7dc
Vorsicht
Sie müssen den Webhook-Endpoint direkt mit der /v1/webhook_endpoints API von Stripe erstellen. Das Objekt collect_inputs gibt keine vollständigen Ergebnisse zurück, wenn Sie den Webhook-Endpoint mit der Stripe-CLI oder den serverseitigen SDKs von Stripe erstellen. Um sicherzustellen, dass das Objekt collect_inputs
in der Webhook-Nutzlast vorhanden ist, fügen Sie terminal_collect_inputs_beta=v1
in den Anfrage-Header ein legen Sie die Eigenschaft api_version
fest, wenn Sie den Webhook-Endpoint erstellen.
Sie können einen vorhandenen Webhook nicht aktualisieren, um erfasste Eingaben zu überwachen, sondern müssen einen neuen erstellen.
Wenn alle Eingaben erfasst oder übersprungen wurden, sendet Stripe eine Anfrage an Ihren Webhook-Endpoint. Die Anfragenutzlast ist identisch mit der Antwort beim Aufruf von collect_inputs, verfügt jedoch über ein paar zusätzliche Parameter:
- Der Parameter
value
wird für jede erfasste Eingabe ausgefüllt. - Wenn eine optionale Eingabe vom Kunden/von der Kundin übersprungen wird, wird der Übersprungen-Parameter auf
true
gesetzt. - Der
value
jedes Umschalters wird mitenabled
oderdisabled
ausgefüllt.
Abonnieren Sie Webhooks, um erfasste Informationen zu erhalten, sobald diese verfügbar sind. Sie können das Lesegerät mit dem terminal_collect_inputs_beta=v1
-Anforderungsheader als Backup abrufen, wenn Ihr Backend den Webhook nicht nutzen kann.
Stripe sendet zwei Webhooks, um Ihr Backend über den Status des Lesegeräts zu informieren:
terminal.reader.action_succeeded
: Wird gesendet, wenn einecollect_inputs
-Aktion erfolgreich ist.terminal.reader.action_failed
: Wird gesendet, wenn einecollect_inputs
-Aktion fehlschlägt. Dies schließt Zeitüberschreitungen ein, die auftreten, nachdem das Lesegerät 2 Minuten lang nicht berührt wurde.
Signaturbilder herunterladen
Um das erfasste Signaturbild zu erhalten, rufen Sie die Datei ab und verwenden Sie Ihren Geheimschlüssel. So können Sie auf die zugehörige URL zugreifen.
Notiz
Stripe speichert die von Ihnen erfassten Signaturbilder 7 Tage lang. Wenn Sie Signaturbilder mehr als 7 Tage nach der Erfassung verwenden müssen, laden Sie die Datei herunter und speichern Sie sie. Sie sind in vollem Umfang dafür verantwortlich, sich über alle Gesetze zu informieren, die in Bezug auf Ihre Verwendung, Speicherung und Offenlegung von Kundenunterschriften gelten.
Beta-SDK
Wenn Sie eines der serverseitigen SDKs von Stripe verwenden, müssen Sie eine Beta-Version installieren. Informationen zur Installation finden Sie auf der entsprechenden GitHub-Seite für das Server-SDK, das Sie verwenden möchten.
Sie müssen auch die API-Version Ihres SDK so konfigurieren, dass sie den oben genannten Beta-Header enthält. Hier finden Sie sprachspezifische Beispiele dafür.
Notiz
Umschalter erfordert Lesegerät-Version 2.21
und höher.