Eingaben auf dem Bildschirm erfassenBeta

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 angeben, welcher Text 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.

E-Mail und Auswahlformular mit Umschalter

Für Auswahl-Eingaben sind zusätzliche Anpassungen verfügbar. Beim Festlegen der Auswahlmöglichkeiten, die den Kundinnen/Kunden angezeigt werden sollen, 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 Nutzdaten der Anfrage enthalten die angegebenen Metadaten, die sowohl in der synchronen Antwort als auch in den Webhooks für Erfolg oder Misserfolg erscheinen. Indem Sie eine eindeutige Kennung wie eine Kunden-ID oder eine Bestell-ID angeben, können Sie den eingehenden Webhook leichter identifizieren und bearbeiten.

curl https://api.stripe.com/v1/terminal/readers/
{{READER_ID}}
/collect_inputs \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Version: 2024-11-20.acacia; terminal_collect_inputs_beta=v1;" \
  -d "inputs[0][type]"=signature \
  -d "inputs[0][custom_text][title]"="Rental Agreement" \
  -d "inputs[0][custom_text][description]"="Please sign below to indicate that you agree to the rental agreement." \
  -d "inputs[0][custom_text][submit_button]"=Submit \
  -d "inputs[0][required]"=true \
  -d "inputs[1][type]"=selection \
  -d "inputs[1][selection][choices][0][style]"=primary \
  -d "inputs[1][selection][choices][0][value]"=Email \
  -d "inputs[1][selection][choices][1][style]"=primary \
  -d "inputs[1][selection][choices][1][value]"=Printed \
  -d "inputs[1][selection][choices][2][style]"=secondary \
  -d "inputs[1][selection][choices][2][value]"="No thanks" \
  -d "inputs[1][custom_text][title]"=Receipt \
  --data-urlencode "inputs[1][custom_text][description]"="How would you like your receipt?" \
  -d "inputs[1][required]"=true \
  -d "inputs[2][type]"=email \
  -d "inputs[2][custom_text][title]"="Enter your email" \
  --data-urlencode "inputs[2][custom_text][description]"="We'll send updates on your order and occasional deals" \
  -d "inputs[2][required]"=true \
  -d "inputs[2][toggles][0][title]"="Opt-in for marketing emails" \
  -d "inputs[2][toggles][0][default_value]"=enabled \
  -d "metadata[order_number]"=12345

Wenn das Lesegerät mit der Erfassung der Eingaben beginnt, zeigt es die erste Eingabe aus der Liste an, die Sie für die Kundin/ den Kunden angegeben haben. Die Kundin/der Kunde muss eine Auswahl treffen, per Signatur unterschreiben oder die Tastatur verwenden, um mit den erforderlichen Eingaben fortzufahren. Für optionale Eingaben besteht die Möglichkeit, zur nächsten angeforderten Eingabe überzugehen.

Nachdem die Kundin/der Kunde alle Eingaben übermittelt oder übersprungen hat, aktualisiert Stripe das Lesegerät-Objekt und versendet den Webhook terminal.reader.action_succeeded. Das Lesegerät wechselt für 3 Sekunden in einen Übergangsstatus, in dem es zu einer nachfolgenden Anfrage übergehen kann. Nach 3 Sekunden wechselt das Lesegerät wieder zurück zum Begrüßungsbildschirm.

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 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  --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"

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.
  • Bei Eingaben vom Typ „Signatur“ ist der Wert eine Datei-ID, die das Signaturbild als SVG abruft.
  • Bei Eingaben vom Typ „Auswahl“ ist der Wert die Zeichenfolge des value der getroffenen Auswahl.
  • Bei Telefon-, E-Mail-, Text- und numerischen Eingaben ist der Wert die Zeichenfolge der Kundenantwort.
• Wenn eine optionale Eingabe von der Kundin/dem Kunden übersprungen wird, wird der Übersprungen-Parameter auf true gesetzt.
• Der value jedes Umschalters wird mit enabled oder disabled 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 eine collect_inputs-Aktion erfolgreich ist.
• terminal.reader.action_failed: Wird gesendet, wenn eine collect_inputs-Aktion fehlschlägt. Dies schließt Zeitüberschreitungen ein, die auftreten, nachdem das Lesegerät 2 Minuten lang nicht berührt wurde.

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.